ExDataSketch.Binary.Validator (ExDataSketch v0.8.0)

Copy Markdown View Source

Structured validation primitives for EXSK frames.

This module exposes the individual checks that ExDataSketch.Binary.Header.decode/1 performs as discrete, composable functions. Tests, fuzzers, and tools (e.g., a hypothetical "exsk inspect" CLI) can use these to surface precisely which check failed without parsing the full frame.

All validators follow a uniform contract:

  • Return :ok on success.
  • Return {:error, %ExDataSketch.Errors.DeserializationError{}} on failure.
  • NEVER crash the BEAM.

See also

Summary

Functions

check_crc(bin)

Verifies the trailing CRC32C of a frame against the recomputed checksum.

check_magic(arg1)

Returns :ok when the leading 4 bytes are the EXSK magic.

check_minimum_v2_size(bin)

Returns :ok when the binary is at least the v2 minimum frame size.

check_version(arg1, expected)

Returns :ok when the frame is the expected version.

Functions

check_crc(bin)

@spec check_crc(binary()) :: :ok | {:error, Exception.t()}

Verifies the trailing CRC32C of a frame against the recomputed checksum.

Accepts the full frame including the trailing 4-byte CRC32C. Returns :ok if the recomputed CRC over bin[0 .. -5] equals the declared trailer; an error otherwise.

Useful in fuzz tests that want to assert a single bit-flip is detected.

Examples

iex> meta = ExDataSketch.Hash.Metadata.new(:xxhash3, 0, 1, 1, :rust)
iex> frame = ExDataSketch.Binary.Header.encode(meta, <<1, 2, 3>>)
iex> ExDataSketch.Binary.Validator.check_crc(frame)
:ok

check_magic(arg1)

@spec check_magic(binary()) :: :ok | {:error, Exception.t()}

Returns :ok when the leading 4 bytes are the EXSK magic.

Examples

iex> ExDataSketch.Binary.Validator.check_magic("EXSK" <> <<0, 0>>)
:ok

iex> match?({:error, _}, ExDataSketch.Binary.Validator.check_magic("BAAD"))
true

check_minimum_v2_size(bin)

@spec check_minimum_v2_size(binary()) :: :ok | {:error, Exception.t()}

Returns :ok when the binary is at least the v2 minimum frame size.

Examples

iex> ExDataSketch.Binary.Validator.check_minimum_v2_size(:binary.copy(<<0>>, 32))
:ok

iex> match?({:error, _}, ExDataSketch.Binary.Validator.check_minimum_v2_size(<<1, 2, 3>>))
true

check_version(arg1, expected)

@spec check_version(binary(), non_neg_integer()) :: :ok | {:error, Exception.t()}

Returns :ok when the frame is the expected version.

Examples

iex> ExDataSketch.Binary.Validator.check_version("EXSK" <> <<2>>, 2)
:ok

iex> match?({:error, _}, ExDataSketch.Binary.Validator.check_version("EXSK" <> <<1>>, 2))
true