Crdt.Patch_codec_binary

Binary codec for patches

Binary codec for Patch.

Encodes/decodes patches in the json-joy binary format. This uses a custom varint encoding (vu57) and CBOR for embedded values.

Binary format:

• Patch: vu57(sid), vu57(time), meta (CBOR), vu57(op_count), ops...
• Timestamps: b1vu56(flag, time) where flag=0 means same session
• Operations: opcode byte (upper 5 bits = opcode, lower 3 bits = small length) Binary opcodes (upper 5 bits of first byte):
• 0: new_con (0 = value follows, 1 = timestamp ref follows)
• 1: new_val (8)
• 2: new_obj (16)
• 3: new_vec (24)
• 4: new_str (32)
• 5: new_bin (40)
• 6: new_arr (48)
• 9: ins_val (72)
• 10: ins_obj (80)
• 11: ins_vec (88)
• 12: ins_str (96)
• 13: ins_bin (104)
• 14: ins_arr (112)
• 16: del (128)
• 17: nop (136)

Buffer Utilities

type encoder = {
  mutable buf : bytes;
  mutable pos : int;
}

Growable byte buffer for encoding

val create_encoder : ?capacity:int -> unit -> encoder

val ensure_capacity : encoder -> int -> unit

val write_u8 : encoder -> int -> unit

val write_bytes : encoder -> bytes -> unit

val write_string : encoder -> string -> unit

val encoder_contents : encoder -> bytes

Varint Encoding (vu57)

val write_vu57 : encoder -> int -> unit

Encode a variable-length unsigned integer (up to 57 bits). Uses 7 bits per byte, MSB=1 means more bytes follow.

val write_b1vu56 : encoder -> bool -> int -> unit

Encode b1vu56: a 1-bit flag + up to 56 bits of value. First byte: MSB = flag, bit 6 = continuation, bits 0-5 = value. If value > 63, more bytes follow using vu57-style continuation.

Varint Decoding

type decoder = {
  data : bytes;
  mutable pos : int;
  len : int;
}

val create_decoder : bytes -> decoder

val read_u8 : decoder -> int

val read_bytes : decoder -> int -> bytes

val read_string : decoder -> int -> string

val read_vu57 : decoder -> int

Decode vu57 varint - handles up to 8 bytes (57 bits)

val read_b1vu56 : decoder -> bool * int

Decode b1vu56: returns (flag, value) - handles up to 8 bytes (56 bits)

CBOR Value Encoding/Decoding

val write_cbor_undefined : encoder -> unit

Write CBOR undefined (0xf7)

val write_cbor_uint : encoder -> int -> unit

Write a CBOR unsigned integer

val write_cbor_negint : encoder -> int -> unit

Write a CBOR negative integer

val write_cbor_string : encoder -> string -> unit

Write a CBOR text string

val write_cbor_bytes : encoder -> bytes -> unit

Write a CBOR byte string

val write_cbor_float : encoder -> float -> unit

Write a CBOR float64

val write_cbor_value : encoder -> Value.t -> unit

Write any Value.t as CBOR via Cbor_simd

val read_cbor_length : decoder -> int -> int

Read CBOR length based on additional info

val read_cbor_value : decoder -> Value.t

Read a CBOR value via Cbor_simd

Timestamp Encoding/Decoding

val write_timestamp : encoder -> patch_sid:int -> Clock.timestamp -> unit

Encode a timestamp. If sid matches patch_sid, use flag=0 (same session).

val read_timestamp : decoder -> patch_sid:int -> Clock.timestamp

Decode a timestamp

val write_timespan : encoder -> patch_sid:int -> Clock.timespan -> unit

Encode a timespan

val read_timespan : decoder -> patch_sid:int -> Clock.timespan

Decode a timespan

Operation Encoding

val binary_opcode : Op.op_data -> int

Binary opcodes (as base values, actual byte = opcode << 3 | length)

val write_operation : encoder -> patch_sid:int -> Op.op_data -> unit

Encode an operation

Operation Decoding

val read_operation : decoder -> patch_sid:int -> Op.op_data

Decode an operation

Patch Encoding

val encode : Patch.t -> bytes

Encode a patch to binary

val encode_hex : Patch.t -> string

Encode a patch to a hex string (for debugging)

Patch Decoding

val read_patch : decoder -> Patch.t

val decode : bytes -> (Patch.t, string) result

Decode a patch from binary

val decode_hex : string -> (Patch.t, string) result

Decode from a hex string

Batch Encoding/Decoding

val encode_batch : Patch.batch -> bytes

Encode a batch to CBOR array of binary patches

val decode_batch : bytes -> (Patch.batch, string) result