Tay.Storage.Segment (tay_core v1.6.1)

Copy Markdown View Source

Physical v1 segment container. See the Phase 2 segment RFC for the byte contract.

Checksums, framing, and sequence continuity establish physical integrity only. No result authorizes repair, semantic replay, or an applied checkpoint.

Summary

Types

footer()
footer_decode_error()
footer_decode_result()
footer_encode_error()
header_decode_error()
header_decode_result()
parse_result()
reduce_result(acc)
store_decode_error()

Functions

decode_footer(bytes, expected \\ %{})
decode_header(bytes, expected \\ %{})
decode_store(bytes)
encode_footer(footer)
encode_header(arg1)
encode_store(store_id)
filename(id)
filename_id(name)
max_bytes()
max_count()
max_id()
min_rotation_bytes()
parse(bytes, options \\ [])

Validates a complete in-memory segment without retaining its records.

reduce(read, size, accumulator, reducer, options \\ [])

Physical reduction; accumulator is returned only on complete success.

reduce_while(read, size, accumulator, visitor, options \\ [])

Halt-aware physical traversal; errors never return a successful prefix accumulator.

scan(read, size, options \\ [])

Validates a segment through bounded positional reads. No writes occur.

Types

footer()

@type footer() :: %{
  id: pos_integer(),
  first_sequence: pos_integer(),
  last_sequence: pos_integer(),
  count: pos_integer(),
  store_id: <<_::128>>,
  segment_crc: non_neg_integer()
}

footer_decode_error()

@type footer_decode_error() ::
  :checksum
  | :count_sequence_relation
  | :invalid_argument
  | :invalid_crc
  | :invalid_first_sequence
  | :invalid_last_sequence
  | :invalid_magic
  | :invalid_record_count
  | :invalid_segment_id
  | :invalid_store_id
  | :reserved_bytes
  | :trailing_footer_bytes
  | {:invalid_version, 0}
  | {:unsupported_flags, byte()}
  | {:unsupported_version, byte()}
  | {:mismatch, atom(), term(), term()}

footer_decode_result()

@type footer_decode_result() ::
  {:ok, footer()} | {:incomplete, 64} | {:error, footer_decode_error()}

footer_encode_error()

@type footer_encode_error() ::
  :count_sequence_relation
  | :invalid_argument
  | :invalid_crc
  | :invalid_first_sequence
  | :invalid_last_sequence
  | :invalid_record_count
  | :invalid_segment_id
  | :invalid_store_id

header_decode_error()

@type header_decode_error() ::
  store_decode_error()
  | :invalid_first_sequence
  | :invalid_segment_id
  | {:mismatch, :id | :store_id, term(), <<_::128>> | pos_integer()}

header_decode_result()

@type header_decode_result() ::
  {:ok,
   %Tay.Storage.Segment{
     bytes: term(),
     count: term(),
     crc_state: term(),
     digest: term(),
     first_sequence: term(),
     footer: term(),
     id: term(),
     identity: term(),
     last_sequence: term(),
     state: term(),
     store_id: term()
   }}
  | {:incomplete, 44}
  | {:error, header_decode_error()}

parse_result()

@type parse_result() ::
  {:error, map()}
  | {:ok,
     %Tay.Storage.Segment{
       bytes: term(),
       count: term(),
       crc_state: term(),
       digest: term(),
       first_sequence: term(),
       footer: term(),
       id: term(),
       identity: term(),
       last_sequence: term(),
       state: term(),
       store_id: term()
     }}
  | {:ok,
     %Tay.Storage.Segment{
       bytes: term(),
       count: term(),
       crc_state: term(),
       digest: term(),
       first_sequence: term(),
       footer: term(),
       id: term(),
       identity: term(),
       last_sequence: term(),
       state: term(),
       store_id: term()
     }, term()}

reduce_result(acc)

@type reduce_result(acc) ::
  {:error, map()}
  | {:ok,
     %Tay.Storage.Segment{
       bytes: term(),
       count: term(),
       crc_state: term(),
       digest: term(),
       first_sequence: term(),
       footer: term(),
       id: term(),
       identity: term(),
       last_sequence: term(),
       state: term(),
       store_id: term()
     }, acc}

store_decode_error()

@type store_decode_error() ::
  :checksum
  | :invalid_argument
  | :invalid_magic
  | :invalid_store_id
  | :reserved_bytes
  | :trailing_store_bytes
  | {:invalid_version, 0}
  | {:unsupported_flags, byte()}
  | {:unsupported_version, byte()}

Functions

decode_footer(bytes, expected \\ %{})

@spec decode_footer(term(), term()) :: footer_decode_result()

decode_header(bytes, expected \\ %{})

@spec decode_header(term(), term()) :: header_decode_result()

decode_store(bytes)

@spec decode_store(term()) ::
  {:ok, <<_::128>>} | {:incomplete, 28} | {:error, store_decode_error()}

encode_footer(footer)

@spec encode_footer(term()) :: {:ok, <<_::512>>} | {:error, footer_encode_error()}

encode_header(arg1)

@spec encode_header(any()) ::
  {:error,
   :invalid_argument
   | :invalid_first_sequence
   | :invalid_segment_id
   | :invalid_store_id}
  | {:ok, <<_::32, _::_*8>>}

encode_store(store_id)

@spec encode_store(any()) :: {:error, :invalid_store_id} | {:ok, <<_::32, _::_*8>>}

filename(id)

@spec filename(any()) :: {:error, :invalid_segment_id} | {:ok, <<_::32, _::_*8>>}

filename_id(name)

@spec filename_id(any()) ::
  {:error, :invalid_segment_id | :invalid_segment_name} | {:ok, integer()}

max_bytes()

@spec max_bytes() :: pos_integer()

max_count()

@spec max_count() :: pos_integer()

max_id()

@spec max_id() :: pos_integer()

min_rotation_bytes()

@spec min_rotation_bytes() :: pos_integer()

parse(bytes, options \\ [])

@spec parse(binary(), keyword()) :: parse_result()

Validates a complete in-memory segment without retaining its records.

reduce(read, size, accumulator, reducer, options \\ [])

@spec reduce(term(), term(), acc, term(), keyword()) :: reduce_result(acc)
when acc: var

Physical reduction; accumulator is returned only on complete success.

reduce_while(read, size, accumulator, visitor, options \\ [])

Halt-aware physical traversal; errors never return a successful prefix accumulator.

scan(read, size, options \\ [])

@spec scan(term(), term(), keyword()) :: parse_result()

Validates a segment through bounded positional reads. No writes occur.