mdl_state_store.c

Go to the documentation of this file.

#include <inttypes.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
 
#include "mdl_state.h"
#include "mdl_state_internal.h"
#include "ra8_attributes.h"

typedef enum : uint32_t {
  k_state_magic_bytes                = 8U,                 
  k_state_header_bytes               = 40U,                
  k_state_header_crc_span            = 36U,                
  k_state_envelope_v1                = 1U,                 
  k_state_alt_suffix                 = 4U,                 
  k_state_io_call_max                = 8U * 1024U * 1024U, 
  k_state_crc32_polynomial           = 0xEDB88320UL,       
  k_state_be32_high_shift            = 24U,                
  k_state_be64_high_shift            = 56U,                
  k_state_header_version_offset      = 8U,                 
  k_state_header_size_offset         = 10U,                
  k_state_header_reserved_offset     = 12U,                
  k_state_header_sequence_offset     = 16U,                
  k_state_header_payload_size_offset = 24U,                
  k_state_header_payload_crc_offset  = 32U,                
  k_state_header_crc_offset          = 36U,                
} mdl_state_store_limit_t;

static const uint8_t s_state_magic[k_state_magic_bytes] = {'M', 'D', 'L', 'S', 'T', 'J', 'N', 'L'};

typedef struct {
  uint64_t sequence;      
  uint64_t payload_bytes; 
  uint32_t payload_crc32; 
} mdl_state_envelope_t;

typedef struct {
  const char*          path;       
  mdl_state_envelope_t envelope;   
  uint64_t             file_bytes; 
  ra8_err_t            error;      
  bool                 exists;     
  bool                 valid;      
  bool                 legacy;     
} mdl_state_slot_t;

typedef struct {
  fw_fs_transaction_t* transaction;   
  uint64_t             payload_bytes; 
  uint32_t             crc_state;     
  uint32_t             calls;         
} mdl_state_writer_t;

typedef struct {
  mdl_storage_t*       storage;  
  mdl_state_envelope_t envelope; 
} mdl_state_validation_t;

RA8_INTERNAL static uint32_t
internal_mdl_state_crc32_update(uint32_t state, const uint8_t* bytes, uint32_t length)
{
  for (uint32_t i = 0U; i < length; ++i) {
    state ^= bytes[i];
    for (uint8_t bit = 0U; bit < 8U; ++bit) {
      const uint32_t mask = (uint32_t)(0U - (state & 1U));
      state               = (state >> 1U) ^ ((uint32_t)k_state_crc32_polynomial & mask);
    }
  }
  return state;
}

RA8_INTERNAL static void internal_mdl_state_put_be16(uint8_t* out, uint16_t value)
{
  out[0] = (uint8_t)(value >> 8U);
  out[1] = (uint8_t)value;
}

RA8_INTERNAL static void internal_mdl_state_put_be32(uint8_t* out, uint32_t value)
{
  out[0] = (uint8_t)(value >> (uint32_t)k_state_be32_high_shift);
  out[1] = (uint8_t)(value >> 16U);
  out[2] = (uint8_t)(value >> 8U);
  out[3] = (uint8_t)value;
}

RA8_INTERNAL static void internal_mdl_state_put_be64(uint8_t* out, uint64_t value)
{
  for (uint8_t i = 0U; i < 8U; ++i) {
    out[i] = (uint8_t)(value >> ((uint32_t)k_state_be64_high_shift - (8U * i)));
  }
}

RA8_INTERNAL static uint16_t internal_mdl_state_get_be16(const uint8_t* in)
{
  return (uint16_t)(((uint16_t)in[0] << 8U) | (uint16_t)in[1]);
}

RA8_INTERNAL static uint32_t internal_mdl_state_get_be32(const uint8_t* in)
{
  return ((uint32_t)in[0] << (uint32_t)k_state_be32_high_shift) | ((uint32_t)in[1] << 16U) |
         ((uint32_t)in[2] << 8U) | (uint32_t)in[3];
}

RA8_INTERNAL static uint64_t internal_mdl_state_get_be64(const uint8_t* in)
{
  uint64_t value = 0U;
  for (uint8_t i = 0U; i < 8U; ++i) {
    value = (value << 8U) | (uint64_t)in[i];
  }
  return value;
}

RA8_INTERNAL static void internal_mdl_state_encode_header(const mdl_state_envelope_t* envelope,
                                                          uint8_t*                    out)
{
  memset(out, 0, (size_t)k_state_header_bytes);
  memcpy(out, s_state_magic, sizeof(s_state_magic));
  internal_mdl_state_put_be16(&out[k_state_header_version_offset], (uint16_t)k_state_envelope_v1);
  internal_mdl_state_put_be16(&out[k_state_header_size_offset], (uint16_t)k_state_header_bytes);
  internal_mdl_state_put_be64(&out[k_state_header_sequence_offset], envelope->sequence);
  internal_mdl_state_put_be64(&out[k_state_header_payload_size_offset], envelope->payload_bytes);
  internal_mdl_state_put_be32(&out[k_state_header_payload_crc_offset], envelope->payload_crc32);
  const uint32_t crc =
    ~internal_mdl_state_crc32_update(UINT32_MAX, out, (uint32_t)k_state_header_crc_span);
  internal_mdl_state_put_be32(&out[k_state_header_crc_offset], crc);
}

RA8_INTERNAL static bool internal_mdl_state_decode_header(const uint8_t*        bytes,
                                                          mdl_state_envelope_t* out)
{
  const uint32_t expected = internal_mdl_state_get_be32(&bytes[k_state_header_crc_offset]);
  const uint32_t actual =
    ~internal_mdl_state_crc32_update(UINT32_MAX, bytes, (uint32_t)k_state_header_crc_span);
  if ((memcmp(bytes, s_state_magic, sizeof(s_state_magic)) != 0) ||
      (internal_mdl_state_get_be16(&bytes[k_state_header_version_offset]) !=
       (uint16_t)k_state_envelope_v1) ||
      (internal_mdl_state_get_be16(&bytes[k_state_header_size_offset]) !=
       (uint16_t)k_state_header_bytes) ||
      (internal_mdl_state_get_be32(&bytes[k_state_header_reserved_offset]) != 0U) ||
      (actual != expected)) {
    return false;
  }
  out->sequence      = internal_mdl_state_get_be64(&bytes[k_state_header_sequence_offset]);
  out->payload_bytes = internal_mdl_state_get_be64(&bytes[k_state_header_payload_size_offset]);
  out->payload_crc32 = internal_mdl_state_get_be32(&bytes[k_state_header_payload_crc_offset]);
  return out->sequence != 0U;
}

RA8_INTERNAL static ra8_err_t
internal_mdl_state_read_all(fw_fs_file_t* file, uint8_t* out, uint32_t length, uint32_t* calls)
{
  uint32_t offset = 0U;
  while (offset < length) {
    if (*calls >= (uint32_t)k_state_io_call_max) {
      return k_ra8_err_invalid_size;
    }
    uint32_t        count = 0U;
    const ra8_err_t err   = fw_fs_read(file, out + offset, length - offset, &count);
    ++(*calls);
    if (err != k_ra8_ok) {
      return err;
    }
    if (count == 0U) {
      return k_ra8_err_invalid_state;
    }
    offset += count;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_hash_payload(mdl_storage_t* storage,
                                                              fw_fs_file_t*  file,
                                                              uint64_t       length,
                                                              uint32_t*      out_crc)
{
  uint64_t remaining = length;
  uint32_t state     = UINT32_MAX;
  uint32_t calls     = 0U;
  while (remaining > 0U) {
    if (calls >= (uint32_t)k_state_io_call_max) {
      return k_ra8_err_invalid_size;
    }
    const uint32_t  wanted = (remaining < (uint64_t)storage->io_buffer_bytes)
                               ? (uint32_t)remaining
                               : storage->io_buffer_bytes;
    uint32_t        count  = 0U;
    const ra8_err_t err    = fw_fs_read(file, storage->io_buffer, wanted, &count);
    ++calls;
    if (err != k_ra8_ok) {
      return err;
    }
    if (count == 0U) {
      return k_ra8_err_invalid_state;
    }
    state = internal_mdl_state_crc32_update(state, storage->io_buffer, count);
    remaining -= count;
  }
  *out_crc = ~state;
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_validate_open(mdl_storage_t*        storage,
                                                               fw_fs_file_t*         file,
                                                               mdl_state_envelope_t* out)
{
  uint64_t  file_bytes = 0U;
  ra8_err_t err        = fw_fs_file_size(file, &file_bytes);
  if ((err != k_ra8_ok) || (file_bytes < (uint64_t)k_state_header_bytes)) {
    return (err == k_ra8_ok) ? k_ra8_err_invalid_state : err;
  }
  err = fw_fs_seek(file, 0U);
  uint8_t  header[k_state_header_bytes];
  uint32_t calls = 0U;
  if (err == k_ra8_ok) {
    err = internal_mdl_state_read_all(file, header, sizeof(header), &calls);
  }
  if ((err != k_ra8_ok) || !internal_mdl_state_decode_header(header, out)) {
    return (err == k_ra8_ok) ? k_ra8_err_invalid_state : err;
  }
  if ((out->payload_bytes > (UINT64_MAX - (uint64_t)k_state_header_bytes)) ||
      (file_bytes != ((uint64_t)k_state_header_bytes + out->payload_bytes))) {
    return k_ra8_err_invalid_state;
  }
  uint32_t crc = 0U;
  err          = internal_mdl_state_hash_payload(storage, file, out->payload_bytes, &crc);
  if (err != k_ra8_ok) {
    return err;
  }
  return (crc == out->payload_crc32) ? k_ra8_ok : k_ra8_err_invalid_state;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_paths(const mdl_storage_t* storage,
                                                       const char*          path,
                                                       char*                base,
                                                       char*                alternate)
{
  if ((storage == nullptr) || (storage->fs == nullptr) || (path == nullptr)) {
    return k_ra8_err_invalid_arg;
  }
  if ((storage->file_workspace == nullptr) || (storage->transaction_workspace == nullptr) ||
      (storage->io_buffer == nullptr) || (storage->io_buffer_bytes == 0U)) {
    return k_ra8_err_invalid_arg;
  }
  ra8_err_t err = fw_fs_path_validate(&storage->fs->caps, path);
  if (err != k_ra8_ok) {
    return err;
  }
  const size_t length = strlen(path);
  if ((length == 0U) || (length + (size_t)k_state_alt_suffix >= (size_t)k_fw_fs_path_cap)) {
    return k_ra8_err_invalid_size;
  }
  memcpy(base, path, length + 1U);
  memcpy(alternate, path, length + 1U);
  memcpy(&alternate[length], ".alt", (size_t)k_state_alt_suffix + 1U);
  return fw_fs_path_validate(&storage->fs->caps, alternate);
}

RA8_INTERNAL static void internal_mdl_state_scan_slot(mdl_storage_t*    storage,
                                                      const char*       path,
                                                      bool              allow_legacy,
                                                      mdl_state_slot_t* out)
{
  *out              = (mdl_state_slot_t){.path = path, .error = k_ra8_ok};
  fw_fs_stat_t stat = {};
  out->error        = fw_fs_stat(&storage->fs->names, path, &stat);
  if ((out->error != k_ra8_ok) || !stat.exists) {
    return;
  }
  out->exists     = true;
  out->file_bytes = stat.size_bytes;
  if (stat.type != k_fw_fs_node_file) {
    out->error = k_ra8_err_invalid_state;
    return;
  }
  fw_fs_file_t file = {};
  out->error        = fw_fs_open(&storage->fs->streams,
                                 path,
                                 k_fw_fs_open_read,
                                 &file,
                                 storage->file_workspace,
                                 storage->file_workspace_bytes);
  if (out->error == k_ra8_ok) {
    uint8_t    prefix[k_state_magic_bytes] = {};
    uint32_t   calls                       = 0U;
    const bool too_short                   = stat.size_bytes < sizeof(prefix);
    out->error =
      too_short ? k_ra8_ok : internal_mdl_state_read_all(&file, prefix, sizeof(prefix), &calls);
    const bool legacy_magic = (out->error == k_ra8_ok) &&
                              (too_short || (memcmp(prefix, s_state_magic, sizeof(prefix)) != 0));
    if (legacy_magic && allow_legacy) {
      out->legacy = true;
      out->valid  = true;
    } else if (legacy_magic) {
      out->error = k_ra8_err_invalid_state;
    } else if (out->error == k_ra8_ok) {
      out->error = internal_mdl_state_validate_open(storage, &file, &out->envelope);
      out->valid = out->error == k_ra8_ok;
    }
  }
  const ra8_err_t closed = file.is_open ? fw_fs_close(&file) : k_ra8_ok;
  if (closed != k_ra8_ok) {
    out->error = closed;
    out->valid = false;
  }
}

RA8_INTERNAL static bool internal_mdl_state_same_generation(const mdl_state_slot_t* a,
                                                            const mdl_state_slot_t* b)
{
  return a->envelope.sequence == b->envelope.sequence &&
         a->envelope.payload_bytes == b->envelope.payload_bytes &&
         a->envelope.payload_crc32 == b->envelope.payload_crc32;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_order(const mdl_state_slot_t*  base,
                                                       const mdl_state_slot_t*  alternate,
                                                       const mdl_state_slot_t** newest,
                                                       const mdl_state_slot_t** older)
{
  *newest = nullptr;
  *older  = nullptr;
  if (!base->valid && !alternate->valid) {
    return k_ra8_ok;
  }
  if (!base->valid || !alternate->valid) {
    *newest = base->valid ? base : alternate;
    return k_ra8_ok;
  }
  if (base->envelope.sequence == alternate->envelope.sequence) {
    if (!internal_mdl_state_same_generation(base, alternate)) {
      return k_ra8_err_invalid_state;
    }
    *newest = base;
    *older  = alternate;
    return k_ra8_ok;
  }
  const bool base_newer = base->envelope.sequence > alternate->envelope.sequence;
  *newest               = base_newer ? base : alternate;
  *older                = base_newer ? alternate : base;
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t
internal_mdl_state_load_slot(mdl_storage_t* storage, const mdl_state_slot_t* slot, mdl_state_t* st)
{
  fw_fs_file_t         file     = {};
  ra8_err_t            err      = fw_fs_open(&storage->fs->streams,
                                             slot->path,
                                             k_fw_fs_open_read,
                                             &file,
                                             storage->file_workspace,
                                             storage->file_workspace_bytes);
  mdl_state_envelope_t observed = {};
  if ((err == k_ra8_ok) && !slot->legacy) {
    err = internal_mdl_state_validate_open(storage, &file, &observed);
    if ((err == k_ra8_ok) && ((observed.sequence != slot->envelope.sequence) ||
                              (observed.payload_bytes != slot->envelope.payload_bytes) ||
                              (observed.payload_crc32 != slot->envelope.payload_crc32))) {
      err = k_ra8_err_invalid_state;
    }
  }
  if (err == k_ra8_ok) {
    const uint64_t offset = slot->legacy ? 0U : (uint64_t)k_state_header_bytes;
    const uint64_t length = slot->legacy ? slot->file_bytes : slot->envelope.payload_bytes;
    const uint16_t max_schema =
      slot->legacy ? (uint16_t)k_mdl_state_version_v2 : (uint16_t)k_mdl_state_version;
    err = priv_mdl_state_parse_file(storage, &file, offset, length, max_schema, st);
  }
  const ra8_err_t closed = file.is_open ? fw_fs_close(&file) : k_ra8_ok;
  if (closed != k_ra8_ok) {
    err = closed;
  }
  if (err != k_ra8_ok) {
    mdl_state_init(st);
  }
  return err;
}

RA8_INTERNAL static ra8_err_t
internal_mdl_state_write_all(mdl_state_writer_t* writer, const uint8_t* bytes, uint32_t length)
{
  uint32_t offset = 0U;
  while (offset < length) {
    if (writer->calls >= (uint32_t)k_state_io_call_max) {
      return k_ra8_err_invalid_size;
    }
    uint32_t        count = 0U;
    const ra8_err_t err =
      fw_fs_transaction_write(writer->transaction, bytes + offset, length - offset, &count);
    ++writer->calls;
    if (err != k_ra8_ok) {
      return err;
    }
    if (count == 0U) {
      return k_ra8_err_invalid_state;
    }
    offset += count;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t
internal_mdl_state_emit(mdl_state_writer_t* writer, const char* line, int length)
{
  if ((length < 0) || ((size_t)length >= (size_t)k_mdl_state_line_max) ||
      (writer->payload_bytes > (UINT64_MAX - (uint64_t)(uint32_t)length))) {
    return k_ra8_err_invalid_size;
  }
  const ra8_err_t err =
    internal_mdl_state_write_all(writer, (const uint8_t*)line, (uint32_t)length);
  if (err != k_ra8_ok) {
    return err;
  }
  writer->crc_state =
    internal_mdl_state_crc32_update(writer->crc_state, (const uint8_t*)line, (uint32_t)length);
  writer->payload_bytes += (uint64_t)(uint32_t)length;
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t
internal_mdl_state_emit_kv(mdl_state_writer_t* writer, char type, const char* value)
{
  char      line[k_mdl_state_line_max];
  const int length = snprintf(line, sizeof(line), "%c\t%s\n", type, value);
  return internal_mdl_state_emit(writer, line, length);
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_emit_metadata(mdl_state_writer_t* writer,
                                                               const mdl_state_t*  st)
{
  static const char types[]  = {'S', 'T', 'N', 'H', 'G', 'D', 'W', 'A', 'O', 'K', 'L'};
  const char* const values[] = {st->series_url,
                                st->series_title,
                                st->site_name,
                                st->site_host,
                                st->config_path,
                                st->summary,
                                st->writer,
                                st->artist,
                                st->cover_url,
                                st->cover_path,
                                st->language};
  ra8_err_t         err      = k_ra8_ok;
  for (size_t i = 0U; (i < sizeof(types)) && (err == k_ra8_ok); ++i) {
    err = internal_mdl_state_emit_kv(writer, types[i], values[i]);
  }
  if (err == k_ra8_ok) {
    char      line[k_mdl_state_line_max];
    const int length = snprintf(line, sizeof(line), "R\t%u\n", (unsigned)st->reading_direction);
    err              = internal_mdl_state_emit(writer, line, length);
  }
  return err;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_emit_chapters(mdl_state_writer_t* writer,
                                                               const mdl_state_t*  st)
{
  char      line[k_mdl_state_line_max];
  ra8_err_t err = k_ra8_ok;
  for (uint16_t i = 0U; (i < st->chapter_count) && (err == k_ra8_ok); ++i) {
    const mdl_chapter_rec_t* chapter     = &st->chapters[i];
    uint64_t                 number_bits = 0U;
    memcpy(&number_bits, &chapter->number, sizeof(number_bits));
    const int length = snprintf(line,
                                sizeof(line),
                                "C\t%s\t%u\t%016" PRIx64 "\t%u\t%u\t%u\t%" PRId64 "\t%s\t%s\n",
                                chapter->chapter_id,
                                chapter->number_known ? 1U : 0U,
                                number_bits,
                                chapter->complete ? 1U : 0U,
                                (unsigned)chapter->page_count,
                                (unsigned)chapter->pages_done,
                                chapter->fetched_at,
                                chapter->source_url,
                                chapter->title);
    err              = internal_mdl_state_emit(writer, line, length);
  }
  return err;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_emit_pages(mdl_state_writer_t* writer,
                                                            const mdl_state_t*  st)
{
  char      line[k_mdl_state_line_max];
  ra8_err_t err = k_ra8_ok;
  for (uint32_t i = 0U; (i < st->page_rec_count) && (err == k_ra8_ok); ++i) {
    const mdl_page_rec_t* page = &st->pages[i];
    const int length = snprintf(line,
                                sizeof(line),
                                "P\t%016" PRIx64 "\t%016" PRIx64 "\t%s\t%s\t%s\t%" PRId64 "\t%u\n",
                                page->url_hash,
                                page->content_hash,
                                page->rel_path,
                                page->etag,
                                page->last_modified,
                                page->fetched_at,
                                (unsigned)page->response_status);
    err              = internal_mdl_state_emit(writer, line, length);
  }
  return err;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_serialize(mdl_state_writer_t* writer,
                                                           const mdl_state_t*  st)
{
  char      line[k_mdl_state_line_max];
  const int length = snprintf(line,
                              sizeof(line),
                              "# mdl library state v%u\nV\t%u\n",
                              (unsigned)k_mdl_state_version,
                              (unsigned)k_mdl_state_version);
  ra8_err_t err    = internal_mdl_state_emit(writer, line, length);
  if (err == k_ra8_ok) {
    err = internal_mdl_state_emit_metadata(writer, st);
  }
  if (err == k_ra8_ok) {
    err = internal_mdl_state_emit_chapters(writer, st);
  }
  return (err == k_ra8_ok) ? internal_mdl_state_emit_pages(writer, st) : err;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_validate_stage(void* ctx, fw_fs_file_t* staged)
{
  if ((ctx == nullptr) || (staged == nullptr)) {
    return k_ra8_err_invalid_arg;
  }
  const mdl_state_validation_t* expected = (const mdl_state_validation_t*)ctx;
  mdl_state_envelope_t          observed = {};
  const ra8_err_t err = internal_mdl_state_validate_open(expected->storage, staged, &observed);
  if (err != k_ra8_ok) {
    return err;
  }
  if ((observed.sequence != expected->envelope.sequence) ||
      (observed.payload_bytes != expected->envelope.payload_bytes) ||
      (observed.payload_crc32 != expected->envelope.payload_crc32)) {
    return k_ra8_err_protocol_error;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_abort(fw_fs_transaction_t* transaction,
                                                       ra8_err_t            primary)
{
  if (!transaction->active) {
    return primary;
  }
  const ra8_err_t aborted = fw_fs_transaction_abort(transaction);
  return (aborted == k_ra8_ok) ? primary : aborted;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_build_stage(mdl_storage_t*        storage,
                                                             const char*           target,
                                                             uint64_t              sequence,
                                                             const mdl_state_t*    st,
                                                             fw_fs_transaction_t*  transaction,
                                                             mdl_state_envelope_t* envelope)
{
  ra8_err_t          err    = fw_fs_transaction_begin(&storage->fs->transactions,
                                                      target,
                                                      k_fw_fs_txn_create_new,
                                                      transaction,
                                                      storage->transaction_workspace,
                                                      storage->transaction_workspace_bytes);
  mdl_state_writer_t writer = {.transaction   = transaction,
                               .payload_bytes = 0U,
                               .crc_state     = UINT32_MAX,
                               .calls         = 0U};
  if (err == k_ra8_ok) {
    const uint8_t placeholder[k_state_header_bytes] = {};
    err = internal_mdl_state_write_all(&writer, placeholder, sizeof(placeholder));
  }
  if (err == k_ra8_ok) {
    err = internal_mdl_state_serialize(&writer, st);
  }
  *envelope = (mdl_state_envelope_t){.sequence      = sequence,
                                     .payload_bytes = writer.payload_bytes,
                                     .payload_crc32 = ~writer.crc_state};
  uint8_t header[k_state_header_bytes];
  internal_mdl_state_encode_header(envelope, header);
  if (err == k_ra8_ok) {
    err = fw_fs_transaction_seek(transaction, 0U);
  }
  if (err == k_ra8_ok) {
    err = internal_mdl_state_write_all(&writer, header, sizeof(header));
  }
  const mdl_state_validation_t validation = {.storage = storage, .envelope = *envelope};
  return (err == k_ra8_ok) ? fw_fs_transaction_validate(transaction,
                                                        internal_mdl_state_validate_stage,
                                                        (void*)&validation)
                           : err;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_save_plan(const mdl_state_slot_t*  base,
                                                           const mdl_state_slot_t*  alternate,
                                                           const mdl_state_slot_t** target,
                                                           uint64_t*                sequence)
{
  const mdl_state_slot_t* newest = nullptr;
  const mdl_state_slot_t* older  = nullptr;
  ra8_err_t               err    = internal_mdl_state_order(base, alternate, &newest, &older);
  if (err != k_ra8_ok) {
    return err;
  }
  if (newest == nullptr) {
    if ((base->error != k_ra8_ok) || (alternate->error != k_ra8_ok)) {
      return (base->error != k_ra8_ok) ? base->error : alternate->error;
    }
    *target   = base;
    *sequence = 1U;
    return k_ra8_ok;
  }
  if (newest->envelope.sequence == UINT64_MAX) {
    return k_ra8_err_invalid_size;
  }
  *target = (newest == base) ? alternate : base;
  if ((older != nullptr) && (*target != older)) {
    return k_ra8_err_invalid_state;
  }
  if (!(*target)->exists && ((*target)->error != k_ra8_ok)) {
    return (*target)->error;
  }
  *sequence = newest->envelope.sequence + 1U;
  return k_ra8_ok;
}
 
ra8_err_t mdl_state_probe(mdl_storage_t* storage, const char* path, bool* out_exists)
{
  if (out_exists == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  *out_exists = false;
  char      base[k_fw_fs_path_cap];
  char      alternate[k_fw_fs_path_cap];
  ra8_err_t err = internal_mdl_state_paths(storage, path, base, alternate);
  if (err != k_ra8_ok) {
    return err;
  }
  const char* paths[] = {base, alternate};
  for (size_t i = 0U; i < 2U; ++i) {
    fw_fs_stat_t stat = {};
    err               = fw_fs_stat(&storage->fs->names, paths[i], &stat);
    if (err != k_ra8_ok) {
      return err;
    }
    if (stat.exists && (stat.type != k_fw_fs_node_file)) {
      return k_ra8_err_invalid_state;
    }
    *out_exists = *out_exists || stat.exists;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_load_mode(mdl_storage_t* storage,
                                                           const char*    path,
                                                           mdl_state_t*   st,
                                                           bool           allow_legacy)
{
  if (st == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  mdl_state_init(st);
  char      base_path[k_fw_fs_path_cap];
  char      alternate_path[k_fw_fs_path_cap];
  ra8_err_t err = internal_mdl_state_paths(storage, path, base_path, alternate_path);
  if (err != k_ra8_ok) {
    return err;
  }
  mdl_state_slot_t base;
  mdl_state_slot_t alternate;
  internal_mdl_state_scan_slot(storage, base_path, allow_legacy, &base);
  internal_mdl_state_scan_slot(storage, alternate_path, false, &alternate);
  const mdl_state_slot_t* newest = nullptr;
  const mdl_state_slot_t* older  = nullptr;
  err                            = internal_mdl_state_order(&base, &alternate, &newest, &older);
  if (err != k_ra8_ok) {
    return err;
  }
  if (newest == nullptr) {
    if (!base.exists && !alternate.exists && (base.error == k_ra8_ok) &&
        (alternate.error == k_ra8_ok)) {
      return k_ra8_ok;
    }
    return (base.error != k_ra8_ok) ? base.error : alternate.error;
  }
  err = internal_mdl_state_load_slot(storage, newest, st);
  if ((err != k_ra8_ok) && (older != nullptr)) {
    err = internal_mdl_state_load_slot(storage, older, st);
  }
  return err;
}
 
ra8_err_t mdl_state_load(mdl_storage_t* storage, const char* path, mdl_state_t* st)
{
  return internal_mdl_state_load_mode(storage, path, st, true);
}
 
ra8_err_t mdl_state_load_authenticated(mdl_storage_t* storage, const char* path, mdl_state_t* st)
{
  return internal_mdl_state_load_mode(storage, path, st, false);
}

RA8_INTERNAL static ra8_err_t internal_mdl_state_prepare_target(mdl_storage_t* storage,
                                                                const char*    path,
                                                                char*          base,
                                                                char*          alternate,
                                                                const char**   out_target,
                                                                uint64_t*      out_sequence)
{
  ra8_err_t err = internal_mdl_state_paths(storage, path, base, alternate);
  if (err != k_ra8_ok) {
    return err;
  }
  mdl_state_slot_t base_slot;
  mdl_state_slot_t alternate_slot;
  internal_mdl_state_scan_slot(storage, base, true, &base_slot);
  internal_mdl_state_scan_slot(storage, alternate, false, &alternate_slot);
  const mdl_state_slot_t* target = nullptr;
  err = internal_mdl_state_save_plan(&base_slot, &alternate_slot, &target, out_sequence);
  if (err != k_ra8_ok) {
    return err;
  }
  if (target->exists) {
    err = fw_fs_unlink(&storage->fs->names, target->path);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  *out_target = target->path;
  return k_ra8_ok;
}
 
ra8_err_t
mdl_state_save(mdl_storage_t* storage, const char* path, const mdl_state_t* st, bool* out_published)
{
  if (out_published == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  *out_published = false;
  if ((st == nullptr) || !priv_mdl_state_valid(st)) {
    return (st == nullptr) ? k_ra8_err_invalid_arg : k_ra8_err_invalid_state;
  }
  char        base_path[k_fw_fs_path_cap];
  char        alternate_path[k_fw_fs_path_cap];
  const char* target   = nullptr;
  uint64_t    sequence = 0U;
  ra8_err_t   err =
    internal_mdl_state_prepare_target(storage, path, base_path, alternate_path, &target, &sequence);
  if (err != k_ra8_ok) {
    return err;
  }
  fw_fs_transaction_t  transaction = {};
  mdl_state_envelope_t envelope    = {};
  err = internal_mdl_state_build_stage(storage, target, sequence, st, &transaction, &envelope);
  if (err != k_ra8_ok) {
    return internal_mdl_state_abort(&transaction, err);
  }
  bool published = false;
  err            = fw_fs_transaction_commit(&transaction, &published);
  *out_published = published;
  if (published) {
    return err;
  }
  if (err == k_ra8_ok) {
    err = k_ra8_err_invalid_state;
  }
  return internal_mdl_state_abort(&transaction, err);
}