OmniBuf.Wire (omnibuf v0.1.0)

Copy Markdown View Source

Low-level OmniBuf v0.1 wire primitives: 1/2/4/9-byte Prefix-Varints, 64-bit ZigZag, all 16 wire types, IEEE-754 float handling, O(1) sub-binary field skipping, and container/depth validation.

Summary

Functions

Decodes a WireArray header: [ByteLen][ElementType: 1B][Count]. Validates bounds, element type, Count = 0 trailing bytes, and count/remaining invariants.

Reads a length-prefixed slice as a zero-copy sub-binary, checking bounds first.

Decodes a WireMap header: [ByteLen][KeyType: 1B][ValueType: 1B][Count]. Validates bounds, key/value types, Count = 0 trailing bytes, and count <= remaining / 2.

Reads a length-prefixed UTF-8 string and strictly validates UTF-8.

Decodes a field tag, validating field number bounds and Field #0 wire type (WireSubMsg).

Decodes a Prefix-Varint (accepting non-minimal widths and rejecting reserved prefixes).

Wraps iodata with a Prefix-Varint byte-length prefix.

Encodes (field_number << 4) | wire_type as a Prefix-Varint.

Encodes a non-negative 64-bit integer as a minimal Prefix-Varint binary.

Returns the fixed byte width of a collection element wire type, or nil if variable-width.

Skips a single wire value in O(1) time without inspecting container internals. Used by lazy Opaque field scanning.

Skips a wire value while validating container bounds, nesting depth (max 32), and Field #0 wire type invariants inside unknown submessages. Unread WireString payloads are skipped in O(1) by ByteLen.

Returns true if code is a valid WireArray ElementType or WireMap ValueType. High 4 bits must be 0 and code 3 (WireBoolTrue) is invalid in collections.

Returns true if code is a valid WireMap KeyType. Valid codes: 0, 1, 2, 4, 5, 6, 7, 10.

Validates an entire message field stream (for unknown submessages).

Functions

decode_array_header(bin, max_elements \\ 1_000_000)

@spec decode_array_header(binary(), non_neg_integer()) ::
  {:ok, 0..15, non_neg_integer(), binary(), binary()}
  | {:error, OmniBuf.Error.t()}

Decodes a WireArray header: [ByteLen][ElementType: 1B][Count]. Validates bounds, element type, Count = 0 trailing bytes, and count/remaining invariants.

decode_float32(arg1)

@spec decode_float32(binary()) ::
  {:ok, float() | :infinity | :neg_infinity | :nan, binary()}
  | {:error, OmniBuf.Error.t()}

decode_float64(arg1)

@spec decode_float64(binary()) ::
  {:ok, float() | :infinity | :neg_infinity | :nan, binary()}
  | {:error, OmniBuf.Error.t()}

decode_length_prefixed(bin)

@spec decode_length_prefixed(binary()) ::
  {:ok, binary(), binary()} | {:error, OmniBuf.Error.t()}

Reads a length-prefixed slice as a zero-copy sub-binary, checking bounds first.

decode_map_header(bin, max_elements \\ 1_000_000)

@spec decode_map_header(binary(), non_neg_integer()) ::
  {:ok, 0..15, 0..15, non_neg_integer(), binary(), binary()}
  | {:error, OmniBuf.Error.t()}

Decodes a WireMap header: [ByteLen][KeyType: 1B][ValueType: 1B][Count]. Validates bounds, key/value types, Count = 0 trailing bytes, and count <= remaining / 2.

decode_string(bin)

@spec decode_string(binary()) ::
  {:ok, String.t(), binary()} | {:error, OmniBuf.Error.t()}

Reads a length-prefixed UTF-8 string and strictly validates UTF-8.

decode_tag(bin)

@spec decode_tag(binary()) ::
  {:ok, non_neg_integer(), 0..15, binary()} | {:error, OmniBuf.Error.t()}

Decodes a field tag, validating field number bounds and Field #0 wire type (WireSubMsg).

decode_varint(arg1)

@spec decode_varint(binary()) ::
  {:ok, non_neg_integer(), binary()} | {:error, OmniBuf.Error.t()}

Decodes a Prefix-Varint (accepting non-minimal widths and rejecting reserved prefixes).

decode_zigzag(u)

@spec decode_zigzag(non_neg_integer()) :: integer()

default_max_elements()

encode_float32(v)

@spec encode_float32(number() | :infinity | :neg_infinity | :nan) :: binary()

encode_float64(v)

@spec encode_float64(number() | :infinity | :neg_infinity | :nan) :: binary()

encode_length_prefixed(body)

@spec encode_length_prefixed(iodata()) :: iodata()

Wraps iodata with a Prefix-Varint byte-length prefix.

encode_tag(field_number, wire_type)

@spec encode_tag(non_neg_integer(), 0..15) :: binary()

Encodes (field_number << 4) | wire_type as a Prefix-Varint.

encode_varint(v)

@spec encode_varint(non_neg_integer()) :: binary()

Encodes a non-negative 64-bit integer as a minimal Prefix-Varint binary.

encode_zigzag(n)

@spec encode_zigzag(integer()) :: non_neg_integer()

fixed_width(arg1)

@spec fixed_width(0..15) :: pos_integer() | nil

Returns the fixed byte width of a collection element wire type, or nil if variable-width.

max_depth()

max_field_number()

narrow_int32(n)

@spec narrow_int32(integer()) :: integer()

narrow_uint32(n)

@spec narrow_uint32(non_neg_integer()) :: non_neg_integer()

skip_fast(wt, bin)

@spec skip_fast(0..15, binary()) :: {:ok, binary()} | {:error, OmniBuf.Error.t()}

Skips a single wire value in O(1) time without inspecting container internals. Used by lazy Opaque field scanning.

skip_validated(wt, bin, depth)

@spec skip_validated(0..15, binary(), non_neg_integer()) ::
  {:ok, binary()} | {:error, OmniBuf.Error.t()}

Skips a wire value while validating container bounds, nesting depth (max 32), and Field #0 wire type invariants inside unknown submessages. Unread WireString payloads are skipped in O(1) by ByteLen.

valid_element_type?(code)

@spec valid_element_type?(integer()) :: boolean()

Returns true if code is a valid WireArray ElementType or WireMap ValueType. High 4 bits must be 0 and code 3 (WireBoolTrue) is invalid in collections.

valid_key_type?(code)

@spec valid_key_type?(integer()) :: boolean()

Returns true if code is a valid WireMap KeyType. Valid codes: 0, 1, 2, 4, 5, 6, 7, 10.

validate_message_stream(bin, depth)

@spec validate_message_stream(binary(), non_neg_integer()) ::
  :ok | {:error, OmniBuf.Error.t()}

Validates an entire message field stream (for unknown submessages).

wire_array()

wire_bool_false()

wire_bool_true()

wire_bytes()

wire_extended()

wire_fixed32()

wire_fixed64()

wire_float32()

wire_float64()

wire_map()

wire_sfixed32()

wire_sfixed64()

wire_sint()

wire_string()

wire_sub_msg()

wire_uint()