book_stream.c

Go to the documentation of this file.

#include "book_stream.h"
 
#include <string.h>
 
#include "book_internal.h"
#include "book_stream_internal.h"
#include "ra8_attributes.h"
 
/*
 * @brief Validate the four metadata strings and optional cover index.
 * @details Validates every metadata string boundary and requires any non-nil
 *          cover reference to select an existing image descriptor.
 * @param[in] ctx Validation state.
 * @return Metadata validation status.
 * @retval k_ra8_ok All metadata references are valid.
 * @retval k_ra8_err_invalid_arg A string or cover-image reference is invalid.
 * @pre Header and string envelope are valid.
 * @pre Image count and metadata offsets are decoded from the validated header.
 * @post No state is modified.
 * @post Success makes all metadata references safe for later lookup.
 * @note Not thread-safe with respect to the source callback.
 * @since Version 0.1.0
 */
RA8_PRIV ra8_err_t priv_book_stream_validate_metadata(const stream_validate_t* ctx)
{
  const uint32_t refs[4] = {
    ctx->hdr.title_off,
    ctx->hdr.author_off,
    ctx->hdr.language_off,
    ctx->hdr.identifier_off,
  };
  for (uint8_t i = 0U; i < (uint8_t)(sizeof(refs) / sizeof(refs[0])); ++i) {
    const ra8_err_t err = priv_book_stream_string_ref(ctx, refs[i]);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  if ((ctx->hdr.cover_image_index != (uint32_t)k_book_nil) &&
      (ctx->hdr.cover_image_index >= ctx->hdr.image_count)) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_validate_chapters(const stream_validate_t* ctx)
{
  uint8_t rec[k_book_sizeof_chapter] = {};
  for (uint32_t i = 0U; i < ctx->hdr.chapter_count; ++i) {
    const uint64_t off =
      (uint64_t)ctx->hdr.chapter_off + ((uint64_t)i * (uint64_t)k_book_sizeof_chapter);
    ra8_err_t err = priv_book_stream_read(ctx, off, rec, (uint32_t)sizeof(rec));
    if (err != k_ra8_ok) {
      return err;
    }
    err = priv_book_stream_string_ref(ctx, internal_book_stream_le32(&rec[0]));
    if (err == k_ra8_ok) {
      err = priv_book_stream_nonempty_string_ref(ctx, internal_book_stream_le32(&rec[4]));
    }
    const uint32_t root = internal_book_stream_le32(&rec[8]);
    if ((err == k_ra8_ok) && (root >= ctx->hdr.node_count)) {
      err = k_ra8_err_invalid_arg;
    }
    if (err == k_ra8_ok) {
      uint8_t node[k_book_sizeof_node] = {};
      err = priv_book_stream_read(ctx,
                                  (uint64_t)ctx->hdr.node_off +
                                    ((uint64_t)root * (uint64_t)k_book_sizeof_node),
                                  node,
                                  (uint32_t)sizeof(node));
      if ((err == k_ra8_ok) && ((node[k_stream_node_kind] != (uint8_t)k_book_node_element) ||
                                (internal_book_stream_le32(&node[k_stream_node_next_sibling]) !=
                                 (uint32_t)k_book_nil))) {
        err = k_ra8_err_invalid_arg;
      }
    }
    if (err == k_ra8_ok) {
      const uint32_t byte = root / 8U;
      const uint8_t  mask = (uint8_t)(1U << (root % 8U));
      if ((ctx->scratch[byte] & mask) != 0U) {
        err = k_ra8_err_invalid_arg;
      } else {
        ctx->scratch[byte] |= mask;
      }
    }
    if (err != k_ra8_ok) {
      return err;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_forward_link(uint32_t link, uint32_t current, uint32_t count)
{
  if (link == (uint32_t)k_book_nil) {
    return k_ra8_ok;
  }
  if ((link <= current) || (link >= count)) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t
internal_mark_forward_link(const stream_validate_t* ctx, uint32_t link, uint32_t current)
{
  const ra8_err_t err = internal_forward_link(link, current, ctx->hdr.node_count);
  if ((err != k_ra8_ok) || (link == (uint32_t)k_book_nil)) {
    return err;
  }
  const uint32_t byte = link / 8U;
  const uint8_t  mask = (uint8_t)(1U << (link % 8U));
  if ((ctx->scratch[byte] & mask) != 0U) {
    return k_ra8_err_invalid_arg;
  }
  ctx->scratch[byte] |= mask;
  return k_ra8_ok;
}
 
/*
 * @brief Validate one element node and advance canonical attribute ownership.
 * @details Requires element-only fields, a non-empty name, and either no
 *          attributes or the exact next contiguous attribute-table span.
 * @param[in] ctx Validation state.
 * @param[in] rec Decoded-wire node bytes.
 * @param[in,out] attr_cursor Next unowned attribute index.
 * @return Element validation status.
 * @retval k_ra8_ok The element fields and attribute span are canonical.
 * @retval k_ra8_err_invalid_arg An element invariant or reference is invalid.
 * @pre Node kind is element and @p attr_cursor is in range.
 * @pre @p rec addresses one complete node wire record.
 * @post Success consumes exactly the node's contiguous attribute span.
 * @post Failure never advances beyond the advertised attribute count.
 * @note Not thread-safe with respect to the source callback.
 * @since Version 0.1.0
 */
RA8_PRIV ra8_err_t priv_book_stream_validate_element(const stream_validate_t* ctx,
                                                     const uint8_t*           rec,
                                                     uint32_t*                attr_cursor)
{
  if (internal_book_stream_le32(&rec[k_stream_node_text]) != 0U) {
    return k_ra8_err_invalid_arg;
  }
  ra8_err_t err =
    priv_book_stream_nonempty_string_ref(ctx, internal_book_stream_le32(&rec[k_stream_node_name]));
  if (err != k_ra8_ok) {
    return err;
  }
  const uint32_t first = internal_book_stream_le32(&rec[k_stream_node_first_attr]);
  const uint32_t count = internal_book_stream_le16(&rec[k_stream_node_attr_count]);
  if (count == 0U) {
    return (first == (uint32_t)k_book_nil) ? k_ra8_ok : k_ra8_err_invalid_arg;
  }
  if ((first != *attr_cursor) || (count > (ctx->hdr.attr_count - *attr_cursor))) {
    return k_ra8_err_invalid_arg;
  }
  *attr_cursor += count;
  return k_ra8_ok;
}
 
/*
 * @brief Validate one text-node invariant set.
 * @details Rejects element-only fields on text records, then validates the
 *          text string boundary through the shared string-pool contract.
 * @param[in] ctx Validation state.
 * @param[in] rec Decoded-wire node bytes.
 * @return Text-node validation status.
 * @retval k_ra8_ok The text node fields and string reference are valid.
 * @retval k_ra8_err_invalid_arg An element-only field or string reference is
 * invalid.
 * @pre Node kind is text.
 * @pre @p rec addresses one complete node wire record.
 * @post No state is modified.
 * @post Success proves the node owns no children or attributes.
 * @note Not thread-safe with respect to the source callback.
 * @since Version 0.1.0
 */
RA8_PRIV ra8_err_t priv_book_stream_validate_text(const stream_validate_t* ctx, const uint8_t* rec)
{
  if ((internal_book_stream_le16(&rec[k_stream_node_attr_count]) != 0U) ||
      (internal_book_stream_le32(&rec[k_stream_node_name]) != 0U) ||
      (internal_book_stream_le32(&rec[k_stream_node_first_attr]) != (uint32_t)k_book_nil) ||
      (internal_book_stream_le32(&rec[k_stream_node_first_child]) != (uint32_t)k_book_nil)) {
    return k_ra8_err_invalid_arg;
  }
  return priv_book_stream_string_ref(ctx, internal_book_stream_le32(&rec[k_stream_node_text]));
}

RA8_INTERNAL static ra8_err_t internal_validate_one_node(const stream_validate_t* ctx,
                                                         const uint8_t*           rec,
                                                         uint32_t*                attr_cursor,
                                                         uint32_t                 index)
{
  ra8_err_t err;
  if (rec[k_stream_node_kind] == (uint8_t)k_book_node_element) {
    err = priv_book_stream_validate_element(ctx, rec, attr_cursor);
  } else if (rec[k_stream_node_kind] == (uint8_t)k_book_node_text) {
    err = priv_book_stream_validate_text(ctx, rec);
  } else {
    err = k_ra8_err_invalid_arg;
  }
  if (err == k_ra8_ok) {
    err = internal_mark_forward_link(ctx,
                                     internal_book_stream_le32(&rec[k_stream_node_first_child]),
                                     index);
  }
  if (err == k_ra8_ok) {
    err = internal_mark_forward_link(ctx,
                                     internal_book_stream_le32(&rec[k_stream_node_next_sibling]),
                                     index);
  }
  return err;
}

RA8_INTERNAL static ra8_err_t internal_validate_nodes(const stream_validate_t* ctx)
{
  uint8_t  rec[k_book_sizeof_node] = {};
  uint32_t attr_cursor             = 0U;
  for (uint32_t i = 0U; i < ctx->hdr.node_count; ++i) {
    const uint64_t off = (uint64_t)ctx->hdr.node_off + ((uint64_t)i * (uint64_t)k_book_sizeof_node);
    ra8_err_t      err = priv_book_stream_read(ctx, off, rec, (uint32_t)sizeof(rec));
    if (err != k_ra8_ok) {
      return err;
    }
    if (rec[k_stream_node_reserved] != 0U) {
      return k_ra8_err_invalid_arg;
    }
    err = internal_validate_one_node(ctx, rec, &attr_cursor, i);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  if (attr_cursor != ctx->hdr.attr_count) {
    return k_ra8_err_invalid_arg;
  }
  for (uint32_t i = 0U; i < ctx->hdr.node_count; ++i) {
    const uint8_t mask = (uint8_t)(1U << (i % 8U));
    if ((ctx->scratch[i / 8U] & mask) == 0U) {
      return k_ra8_err_invalid_arg;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_validate_attrs(const stream_validate_t* ctx)
{
  uint8_t rec[k_book_sizeof_attr] = {};
  for (uint32_t i = 0U; i < ctx->hdr.attr_count; ++i) {
    ra8_err_t err = priv_book_stream_read(ctx,
                                          (uint64_t)ctx->hdr.attr_off +
                                            ((uint64_t)i * (uint64_t)k_book_sizeof_attr),
                                          rec,
                                          (uint32_t)sizeof(rec));
    if (err == k_ra8_ok) {
      err = priv_book_stream_nonempty_string_ref(ctx, internal_book_stream_le32(&rec[0]));
    }
    if (err == k_ra8_ok) {
      err = priv_book_stream_string_ref(ctx, internal_book_stream_le32(&rec[4]));
    }
    if (err != k_ra8_ok) {
      return err;
    }
  }
  return k_ra8_ok;
}
 
/*
 * @brief Validate every stylesheet source and scope.
 * @details Validates each stylesheet source string and permits only nil or an
 *          existing chapter index as its optional scope.
 * @param[in] ctx Validation state.
 * @return Stylesheet-table validation status.
 * @retval k_ra8_ok Every stylesheet source and scope is valid.
 * @retval k_ra8_err_invalid_arg A source boundary or scope index is invalid.
 * @pre Header layout and string envelope are valid.
 * @pre Chapter count is the validated table-record count.
 * @post No state is modified.
 * @post Success makes each stylesheet reference safe for later lookup.
 * @note Iteration is bounded by stylesheet_count.
 * @since Version 0.1.0
 */
RA8_PRIV ra8_err_t priv_book_stream_validate_styles(const stream_validate_t* ctx)
{
  uint8_t rec[k_book_sizeof_stylesheet] = {};
  for (uint32_t i = 0U; i < ctx->hdr.stylesheet_count; ++i) {
    ra8_err_t err = priv_book_stream_read(ctx,
                                          (uint64_t)ctx->hdr.stylesheet_off +
                                            ((uint64_t)i * (uint64_t)k_book_sizeof_stylesheet),
                                          rec,
                                          (uint32_t)sizeof(rec));
    if (err == k_ra8_ok) {
      err = priv_book_stream_string_ref(ctx, internal_book_stream_le32(&rec[0]));
    }
    const uint32_t scope = internal_book_stream_le32(&rec[4]);
    if ((err == k_ra8_ok) && (scope != (uint32_t)k_book_nil) && (scope >= ctx->hdr.chapter_count)) {
      err = k_ra8_err_invalid_arg;
    }
    if (err != k_ra8_ok) {
      return err;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_validate_raster(const uint8_t* rec)
{
  const uint32_t width  = internal_book_stream_le16(&rec[k_stream_image_width]);
  const uint32_t height = internal_book_stream_le16(&rec[k_stream_image_height]);
  const uint8_t  pixfmt = rec[k_stream_image_pixfmt];
  if ((width == 0U) || (height == 0U) ||
      ((pixfmt != (uint8_t)k_book_pixfmt_gray4) && (pixfmt != (uint8_t)k_book_pixfmt_gray8))) {
    return k_ra8_err_invalid_arg;
  }
  const uint64_t pixels = (uint64_t)width * (uint64_t)height;
  const uint64_t expect = (pixfmt == (uint8_t)k_book_pixfmt_gray4) ? ((pixels + 1U) / 2U) : pixels;
  // mcdc-deactivated: internal_validate_raster overflow backstop; width and height are decoded from 16-bit wire fields, so `pixels` is at most 65535*65535 == 0xFFFE0001 and `expect` (pixels, or half of it for gray4) can never exceed UINT32_MAX -- the first condition is provably constant-false and no input can flip it.
  if ((expect > (uint64_t)UINT32_MAX) ||
      (internal_book_stream_le32(&rec[k_stream_image_data_size]) != expect) ||
      (internal_book_stream_le32(&rec[k_stream_image_raw_size]) != expect)) {
    return k_ra8_err_invalid_size;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_validate_svg(const uint8_t* rec)
{
  if ((internal_book_stream_le16(&rec[k_stream_image_width]) != 0U) ||
      (internal_book_stream_le16(&rec[k_stream_image_height]) != 0U) ||
      (rec[k_stream_image_pixfmt] != (uint8_t)k_book_pixfmt_gray4)) {
    return k_ra8_err_invalid_arg;
  }
  const uint32_t data_size = internal_book_stream_le32(&rec[k_stream_image_data_size]);
  return ((data_size != 0U) &&
          (data_size == internal_book_stream_le32(&rec[k_stream_image_raw_size])))
           ? k_ra8_ok
           : k_ra8_err_invalid_arg;
}

RA8_INTERNAL static ra8_err_t internal_validate_images(const stream_validate_t* ctx)
{
  uint8_t  rec[k_book_sizeof_image] = {};
  uint32_t pool_cursor              = 0U;
  for (uint32_t i = 0U; i < ctx->hdr.image_count; ++i) {
    ra8_err_t err = priv_book_stream_read(ctx,
                                          (uint64_t)ctx->hdr.image_off +
                                            ((uint64_t)i * (uint64_t)k_book_sizeof_image),
                                          rec,
                                          (uint32_t)sizeof(rec));
    if (err == k_ra8_ok) {
      err =
        priv_book_stream_nonempty_string_ref(ctx,
                                             internal_book_stream_le32(&rec[k_stream_image_id]));
    }
    if ((err == k_ra8_ok) && (internal_book_stream_le16(&rec[k_stream_image_reserved]) != 0U)) {
      err = k_ra8_err_invalid_arg;
    }
    if (err == k_ra8_ok) {
      if (rec[k_stream_image_format] == (uint8_t)k_book_image_gray4) {
        err = internal_validate_raster(rec);
      } else if (rec[k_stream_image_format] == (uint8_t)k_book_image_svg) {
        err = internal_validate_svg(rec);
      } else {
        err = k_ra8_err_invalid_arg;
      }
    }
    const uint32_t data_off  = internal_book_stream_le32(&rec[k_stream_image_data_off]);
    const uint32_t data_size = internal_book_stream_le32(&rec[k_stream_image_data_size]);
    if ((err == k_ra8_ok) &&
        ((data_off != pool_cursor) || (data_size > (ctx->hdr.image_pool_size - pool_cursor)))) {
      err = k_ra8_err_invalid_size;
    }
    if (err != k_ra8_ok) {
      return err;
    }
    pool_cursor += data_size;
  }
  return (pool_cursor == ctx->hdr.image_pool_size) ? k_ra8_ok : k_ra8_err_invalid_size;
}

RA8_INTERNAL static ra8_err_t internal_validate_crc(const stream_validate_t* ctx)
{
  uint64_t at  = (uint64_t)k_book_sizeof_header;
  uint32_t crc = 0U;
  while (at < (uint64_t)ctx->hdr.total_size) {
    uint64_t remain = (uint64_t)ctx->hdr.total_size - at;
    uint32_t span   = ctx->scratch_cap;
    if (remain < (uint64_t)span) {
      span = (uint32_t)remain;
    }
    const ra8_err_t err = priv_book_stream_read(ctx, at, ctx->scratch, span);
    if (err != k_ra8_ok) {
      return err;
    }
    crc = priv_book_crc32_extend(crc, ctx->scratch, span);
    at += span;
  }
  return (crc == ctx->hdr.crc32_val) ? k_ra8_ok : k_ra8_err_range_check_failed;
}

RA8_INTERNAL static ra8_err_t internal_validate_body(stream_validate_t* ctx)
{
  ra8_err_t err = priv_book_stream_read_validate_header(ctx);
  if (err == k_ra8_ok) {
    err = priv_book_stream_validate_string_envelope(ctx);
  }
  if (err == k_ra8_ok) {
    err = priv_book_stream_validate_metadata(ctx);
  }
  if (err == k_ra8_ok) {
    const uint32_t mark_bytes =
      (ctx->hdr.node_count / 8U) + (((ctx->hdr.node_count % 8U) != 0U) ? 1U : 0U);
    (void)memset(ctx->scratch, 0, mark_bytes);
  }
  if (err == k_ra8_ok) {
    err = internal_validate_chapters(ctx);
  }
  if (err == k_ra8_ok) {
    err = internal_validate_nodes(ctx);
  }
  if (err == k_ra8_ok) {
    err = internal_validate_attrs(ctx);
  }
  if (err == k_ra8_ok) {
    err = priv_book_stream_validate_styles(ctx);
  }
  if (err == k_ra8_ok) {
    err = internal_validate_images(ctx);
  }
  if (err == k_ra8_ok) {
    err = internal_validate_crc(ctx);
  }
  return err;
}
 
ra8_err_t book_validate_stream_strict(book_stream_read_fn read,
                                      void*               read_ctx,
                                      uint64_t            source_size,
                                      uint8_t*            scratch,
                                      uint32_t            scratch_cap,
                                      book_header_t*      out_header)
{
  if (out_header == nullptr) {
    return k_ra8_err_null_ptr;
  }
  *out_header = (book_header_t){};
  if ((read == nullptr) || (scratch == nullptr)) {
    return k_ra8_err_null_ptr;
  }
  if ((source_size < (uint64_t)k_book_sizeof_header) || (scratch_cap == 0U)) {
    return k_ra8_err_invalid_size;
  }
  stream_validate_t ctx = {
    .read        = read,
    .read_ctx    = read_ctx,
    .source_size = source_size,
    .scratch     = scratch,
    .scratch_cap = scratch_cap,
    .hdr         = {},
  };
  const ra8_err_t err = internal_validate_body(&ctx);
  if (err == k_ra8_ok) {
    *out_header = ctx.hdr;
  }
  return err;
}