Merge commit '16f8025448e0a99613bae3df99bd127969d69b68' as 'ocaml-sdnv'

.ocamlformat

···
+version = 0.28.1

dune-project

···
+(lang dune 3.0)
+(name sdnv)
+(formatting (enabled_for ocaml))

lib/dune

···
+(library
+ (name sdnv)
+ (public_name sdnv)
+ (libraries bytesrw))

lib/sdnv.ml

···
+(** Self-Delimiting Numeric Values (RFC 6256).
+
+    Variable-length integer encoding used by LTP (CCSDS 734.1-B-1), Bundle
+    Protocol, and other space protocols. *)
+
+(** {1 Encoding} *)
+
+let encoded_length v =
+  if v < 0L then invalid_arg "Sdnv.encoded_length: negative value"
+  else if v = 0L then 1
+  else
+    let rec count v n =
+      if v = 0L then n else count (Int64.shift_right_logical v 7) (n + 1)
+    in
+    count v 0
+
+let encode_to buf off v =
+  if v < 0L then invalid_arg "Sdnv.encode_to: negative value"
+  else if v = 0L then begin
+    Bytes.set_uint8 buf off 0;
+    1
+  end
+  else begin
+    let n = encoded_length v in
+    if off + n > Bytes.length buf then
+      invalid_arg "Sdnv.encode_to: buffer too small";
+    for i = n - 1 downto 0 do
+      let shift = i * 7 in
+      let byte =
+        Int64.to_int (Int64.logand (Int64.shift_right_logical v shift) 0x7FL)
+      in
+      (* Set continuation bit on all but last byte *)
+      let byte = if i > 0 then byte lor 0x80 else byte in
+      Bytes.set_uint8 buf (off + (n - 1 - i)) byte
+    done;
+    n
+  end
+
+let encode v =
+  let n = encoded_length v in
+  let buf = Bytes.create n in
+  let _ = encode_to buf 0 v in
+  buf
+
+(** {1 Decoding} *)
+
+type error = Truncated | Overflow
+
+let pp_error ppf = function
+  | Truncated -> Format.fprintf ppf "truncated SDNV"
+  | Overflow -> Format.fprintf ppf "SDNV overflow"
+
+let decode buf off =
+  let len = Bytes.length buf in
+  let rec loop acc bits_read pos =
+    if bits_read >= 64 then Error Overflow
+    else if pos >= len then Error Truncated
+    else
+      let byte = Bytes.get_uint8 buf pos in
+      let value = byte land 0x7F in
+      let acc = Int64.(logor (shift_left acc 7) (of_int value)) in
+      if byte land 0x80 = 0 then Ok (acc, pos - off + 1)
+      else loop acc (bits_read + 7) (pos + 1)
+  in
+  loop 0L 0 off
+
+let decode_exn buf off =
+  match decode buf off with
+  | Ok v -> v
+  | Error Truncated -> invalid_arg "Sdnv.decode_exn: truncated"
+  | Error Overflow -> invalid_arg "Sdnv.decode_exn: overflow"
+
+(** {1 Streaming with bytesrw} *)
+
+module Slice = Bytesrw.Bytes.Slice
+
+let read r =
+  let rec loop acc bits_read =
+    if bits_read >= 64 then Error Overflow
+    else
+      match Bytesrw.Bytes.Reader.read r with
+      | slice when Slice.is_eod slice -> Error Truncated
+      | slice ->
+          let data = Slice.bytes slice in
+          let first = Slice.first slice in
+          let length = Slice.length slice in
+          let rec process_slice acc bits_read i =
+            if i >= first + length then
+              (* Need more data from next slice *)
+              loop acc bits_read
+            else
+              let byte = Bytes.get_uint8 data i in
+              let value = byte land 0x7F in
+              let acc = Int64.(logor (shift_left acc 7) (of_int value)) in
+              if byte land 0x80 = 0 then begin
+                (* Push back remaining bytes if any *)
+                let consumed = i - first + 1 in
+                if consumed < length then begin
+                  let remaining =
+                    Slice.make data ~first:(i + 1) ~length:(length - consumed)
+                  in
+                  Bytesrw.Bytes.Reader.push_back r remaining
+                end;
+                Ok acc
+              end
+              else if bits_read + 7 >= 64 then Error Overflow
+              else process_slice acc (bits_read + 7) (i + 1)
+          in
+          process_slice acc bits_read first
+  in
+  loop 0L 0
+
+let read_exn r =
+  match read r with
+  | Ok v -> v
+  | Error Truncated -> invalid_arg "Sdnv.read_exn: truncated"
+  | Error Overflow -> invalid_arg "Sdnv.read_exn: overflow"
+
+let write w v =
+  let buf = encode v in
+  let slice = Slice.make buf ~first:0 ~length:(Bytes.length buf) in
+  Bytesrw.Bytes.Writer.write w slice

lib/sdnv.mli

···
+(** Self-Delimiting Numeric Values (RFC 6256).
+
+    Variable-length integer encoding used by LTP (CCSDS 734.1-B-1), Bundle
+    Protocol, and other space protocols. Each byte's high bit indicates
+    continuation (1=more bytes follow, 0=last byte), with 7 bits of data per
+    byte in big-endian order.
+
+    {b Examples:}
+    - 0 encodes as [0x00] (1 byte)
+    - 127 encodes as [0x7F] (1 byte)
+    - 128 encodes as [0x81 0x00] (2 bytes)
+    - 16383 encodes as [0xFF 0x7F] (2 bytes)
+    - 16384 encodes as [0x81 0x80 0x00] (3 bytes)
+
+    {b Reference}: {{:https://datatracker.ietf.org/doc/html/rfc6256}RFC 6256} *)
+
+(** {1 Encoding} *)
+
+val encode : int64 -> bytes
+(** [encode v] encodes [v] as SDNV bytes.
+    @raise Invalid_argument if [v] is negative. *)
+
+val encode_to : bytes -> int -> int64 -> int
+(** [encode_to buf off v] writes SDNV-encoded [v] into [buf] starting at [off].
+    Returns the number of bytes written.
+    @raise Invalid_argument if [v] is negative or buffer too small. *)
+
+val encoded_length : int64 -> int
+(** [encoded_length v] returns the number of bytes needed to encode [v].
+    @raise Invalid_argument if [v] is negative. *)
+
+(** {1 Decoding} *)
+
+type error =
+  | Truncated  (** Not enough bytes to complete decoding *)
+  | Overflow  (** Value would overflow int64 *)
+
+val pp_error : Format.formatter -> error -> unit
+
+val decode : bytes -> int -> (int64 * int, error) result
+(** [decode buf off] decodes an SDNV starting at [off] in [buf]. Returns the
+    decoded value and the number of bytes consumed. *)
+
+val decode_exn : bytes -> int -> int64 * int
+(** [decode_exn buf off] is like [decode] but raises [Invalid_argument] on
+    error. *)
+
+(** {1 Streaming with bytesrw} *)
+
+val read : Bytesrw.Bytes.Reader.t -> (int64, error) result
+(** [read r] reads and decodes an SDNV from bytesrw reader [r]. *)
+
+val read_exn : Bytesrw.Bytes.Reader.t -> int64
+(** [read_exn r] is like [read] but raises [Invalid_argument] on error. *)
+
+val write : Bytesrw.Bytes.Writer.t -> int64 -> unit
+(** [write w v] encodes and writes SDNV [v] to bytesrw writer [w].
+    @raise Invalid_argument if [v] is negative. *)

sdnv.opam

···
+opam-version: "2.0"
+synopsis: "Self-Delimiting Numeric Values (RFC 6256)"
+description: """
+Variable-length integer encoding used by LTP (CCSDS 734.1-B-1), Bundle Protocol,
+and other space protocols. Each byte's high bit indicates continuation, with 7
+bits of data per byte in big-endian order.
+"""
+maintainer: ["Thomas Gazagnaire <[e-mail]>"]
+authors: ["Thomas Gazagnaire <[e-mail]>"]
+license: "ISC"
+homepage: "https://github.com/gazagnaire/ocaml-sdnv"
+bug-reports: "https://github.com/gazagnaire/ocaml-sdnv/issues"
+dev-repo: "git+https://tangled.org/gazagnaire.org/ocaml-sdnv.git"
+depends: [
+  "ocaml" {>= "4.14"}
+  "dune" {>= "3.0"}
+  "bytesrw"
+]
+build: [
+  ["dune" "subst"] {dev}
+  ["dune" "build" "-p" name "-j" jobs]
+]

test/dune

···
+(test
+ (name test_sdnv)
+ (libraries sdnv alcotest))

test/test_sdnv.ml

···
+(** SDNV test vectors from RFC 5326 and RFC 6256.
+
+    Self-Delimiting Numeric Values (SDNV) test vectors from RFC 5326 section 3.1
+    and RFC 6256. Each byte's high bit is a continuation flag (1=more bytes,
+    0=last). The lower 7 bits of each byte carry the value, MSB first. *)
+
+(* {1 Test Helpers} *)
+
+let bytes_of_hex s =
+  let s = String.concat "" (String.split_on_char ' ' s) in
+  let len = String.length s / 2 in
+  let buf = Bytes.create len in
+  for i = 0 to len - 1 do
+    let hex = String.sub s (i * 2) 2 in
+    Bytes.set buf i (Char.chr (int_of_string ("0x" ^ hex)))
+  done;
+  buf
+
+let hex_of_bytes buf =
+  let len = Bytes.length buf in
+  let hex = Buffer.create (len * 2) in
+  for i = 0 to len - 1 do
+    Buffer.add_string hex (Printf.sprintf "%02x" (Char.code (Bytes.get buf i)))
+  done;
+  Buffer.contents hex
+
+(* {1 RFC 5326 Test Vectors}
+
+   From RFC 5326 section 3.1:
+   - 0x7F (127) -> 0x7F
+   - 0xABC (2748) -> 0x95 0x3C
+   - 0x1234 (4660) -> 0xA4 0x34
+   - 0x4234 (16948) -> 0x81 0x84 0x34 *)
+
+let test_rfc5326_0x7f () =
+  (* 0x7F (127) fits in 7 bits -> single byte 01111111 *)
+  let expected = bytes_of_hex "7f" in
+  let actual = Sdnv.encode 0x7FL in
+  Alcotest.(check string)
+    "0x7F encodes to 7F" (hex_of_bytes expected) (hex_of_bytes actual);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, len) ->
+      Alcotest.(check int64) "0x7F decodes back" 0x7FL decoded;
+      Alcotest.(check int) "length" 1 len
+  | Error _ -> Alcotest.fail "decode failed"
+
+let test_rfc5326_0xabc () =
+  (* 0xABC (2748) = 10010101 00111100 (0x95 0x3C) *)
+  let expected = bytes_of_hex "95 3c" in
+  let actual = Sdnv.encode 0xABCL in
+  Alcotest.(check string)
+    "0xABC encodes to 95 3C" (hex_of_bytes expected) (hex_of_bytes actual);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, len) ->
+      Alcotest.(check int64) "0xABC decodes back" 0xABCL decoded;
+      Alcotest.(check int) "length" 2 len
+  | Error _ -> Alcotest.fail "decode failed"
+
+let test_rfc5326_0x1234 () =
+  (* 0x1234 (4660) = 10100100 00110100 (0xA4 0x34) *)
+  let expected = bytes_of_hex "a4 34" in
+  let actual = Sdnv.encode 0x1234L in
+  Alcotest.(check string)
+    "0x1234 encodes to A4 34" (hex_of_bytes expected) (hex_of_bytes actual);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, len) ->
+      Alcotest.(check int64) "0x1234 decodes back" 0x1234L decoded;
+      Alcotest.(check int) "length" 2 len
+  | Error _ -> Alcotest.fail "decode failed"
+
+let test_rfc5326_0x4234 () =
+  (* 0x4234 (16948) = 10000001 10000100 00110100 (0x81 0x84 0x34) *)
+  let expected = bytes_of_hex "81 84 34" in
+  let actual = Sdnv.encode 0x4234L in
+  Alcotest.(check string)
+    "0x4234 encodes to 81 84 34" (hex_of_bytes expected) (hex_of_bytes actual);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, len) ->
+      Alcotest.(check int64) "0x4234 decodes back" 0x4234L decoded;
+      Alcotest.(check int) "length" 3 len
+  | Error _ -> Alcotest.fail "decode failed"
+
+(* {1 Boundary Tests} *)
+
+let test_zero () =
+  (* 0 -> single byte 0x00 *)
+  let expected = bytes_of_hex "00" in
+  let actual = Sdnv.encode 0L in
+  Alcotest.(check string)
+    "0 encodes to 00" (hex_of_bytes expected) (hex_of_bytes actual);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, len) ->
+      Alcotest.(check int64) "0 decodes back" 0L decoded;
+      Alcotest.(check int) "length" 1 len
+  | Error _ -> Alcotest.fail "decode failed"
+
+let test_boundary_127 () =
+  (* 127 = max 1-byte value *)
+  let actual = Sdnv.encode 127L in
+  Alcotest.(check int) "127 is 1 byte" 1 (Bytes.length actual);
+  Alcotest.(check int) "encoded length" 1 (Sdnv.encoded_length 127L);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, _) -> Alcotest.(check int64) "127 roundtrips" 127L decoded
+  | Error _ -> Alcotest.fail "decode failed"
+
+let test_boundary_128 () =
+  (* 128 (0x80) = first 2-byte value: 10000001 00000000 (0x81 0x00) *)
+  let expected = bytes_of_hex "81 00" in
+  let actual = Sdnv.encode 128L in
+  Alcotest.(check string)
+    "128 encodes to 81 00" (hex_of_bytes expected) (hex_of_bytes actual);
+  Alcotest.(check int) "encoded length" 2 (Sdnv.encoded_length 128L);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, len) ->
+      Alcotest.(check int64) "128 decodes back" 128L decoded;
+      Alcotest.(check int) "length" 2 len
+  | Error _ -> Alcotest.fail "decode failed"
+
+let test_boundary_16383 () =
+  (* 16383 (0x3FFF) = max 2-byte value: 11111111 01111111 (0xFF 0x7F) *)
+  let expected = bytes_of_hex "ff 7f" in
+  let actual = Sdnv.encode 0x3FFFL in
+  Alcotest.(check string)
+    "0x3FFF encodes to FF 7F" (hex_of_bytes expected) (hex_of_bytes actual);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, len) ->
+      Alcotest.(check int64) "0x3FFF decodes back" 0x3FFFL decoded;
+      Alcotest.(check int) "length" 2 len
+  | Error _ -> Alcotest.fail "decode failed"
+
+let test_boundary_16384 () =
+  (* 16384 (0x4000) = first 3-byte value: 10000001 10000000 00000000 *)
+  let actual = Sdnv.encode 16384L in
+  Alcotest.(check int) "16384 is 3 bytes" 3 (Bytes.length actual);
+  Alcotest.(check int) "encoded length" 3 (Sdnv.encoded_length 16384L);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, _) -> Alcotest.(check int64) "16384 roundtrips" 16384L decoded
+  | Error _ -> Alcotest.fail "decode failed"
+
+(* {1 Large Value Tests} *)
+
+let test_large_value () =
+  (* Large value: 0x123456789 (4886718345) - requires 5 bytes *)
+  let value = 0x123456789L in
+  let actual = Sdnv.encode value in
+  Alcotest.(check int) "large value needs 5 bytes" 5 (Bytes.length actual);
+  Alcotest.(check int) "encoded length" 5 (Sdnv.encoded_length value);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, _) ->
+      Alcotest.(check int64) "large value roundtrips" value decoded
+  | Error _ -> Alcotest.fail "decode failed"
+
+let test_max_int63 () =
+  (* Max positive int64: 0x7FFFFFFFFFFFFFFF *)
+  let value = Int64.max_int in
+  let actual = Sdnv.encode value in
+  Alcotest.(check int) "max int64 needs 9 bytes" 9 (Bytes.length actual);
+  match Sdnv.decode actual 0 with
+  | Ok (decoded, _) ->
+      Alcotest.(check int64) "max int64 roundtrips" value decoded
+  | Error _ -> Alcotest.fail "decode failed"
+
+(* {1 Error Tests} *)
+
+let test_truncated () =
+  (* 0x80 indicates continuation but no following byte *)
+  let data = bytes_of_hex "80" in
+  match Sdnv.decode data 0 with
+  | Error Sdnv.Truncated -> ()
+  | Error Sdnv.Overflow -> Alcotest.fail "expected Truncated, got Overflow"
+  | Ok _ -> Alcotest.fail "should fail on truncated"
+
+let test_truncated_multi () =
+  (* 0x81 0x80 indicates continuation but missing final byte *)
+  let data = bytes_of_hex "81 80" in
+  match Sdnv.decode data 0 with
+  | Error Sdnv.Truncated -> ()
+  | Error _ -> Alcotest.fail "expected Truncated"
+  | Ok _ -> Alcotest.fail "should fail on truncated"
+
+let test_negative_rejected () =
+  (* Negative values should be rejected at encode time *)
+  try
+    let _ = Sdnv.encode (-1L) in
+    Alcotest.fail "should reject negative"
+  with Invalid_argument _ -> ()
+
+(* {1 Offset Tests} *)
+
+let test_decode_with_offset () =
+  (* Encode two values back-to-back and decode with offset *)
+  let buf = Bytes.create 10 in
+  let len1 = Sdnv.encode_to buf 0 0x7FL in
+  let len2 = Sdnv.encode_to buf len1 0xABCL in
+  Alcotest.(check int) "first len" 1 len1;
+  Alcotest.(check int) "second len" 2 len2;
+  match Sdnv.decode buf 0 with
+  | Ok (v1, consumed1) -> (
+      Alcotest.(check int64) "first value" 0x7FL v1;
+      Alcotest.(check int) "first consumed" 1 consumed1;
+      match Sdnv.decode buf consumed1 with
+      | Ok (v2, consumed2) ->
+          Alcotest.(check int64) "second value" 0xABCL v2;
+          Alcotest.(check int) "second consumed" 2 consumed2
+      | Error _ -> Alcotest.fail "second decode failed")
+  | Error _ -> Alcotest.fail "first decode failed"
+
+(* {1 Roundtrip Tests} *)
+
+let test_roundtrip_powers_of_two () =
+  (* Test all powers of 2 up to 2^62 *)
+  let rec test_power n =
+    if n > 62 then ()
+    else begin
+      let value = Int64.shift_left 1L n in
+      let encoded = Sdnv.encode value in
+      match Sdnv.decode encoded 0 with
+      | Ok (decoded, _) ->
+          Alcotest.(check int64)
+            (Printf.sprintf "2^%d roundtrips" n)
+            value decoded;
+          test_power (n + 1)
+      | Error _ -> Alcotest.fail (Printf.sprintf "decode failed for 2^%d" n)
+    end
+  in
+  test_power 0
+
+let test_roundtrip_powers_of_two_minus_one () =
+  (* Test 2^n - 1 values (all 1s in binary) *)
+  let rec test_power n =
+    if n > 62 then ()
+    else begin
+      let value = Int64.sub (Int64.shift_left 1L n) 1L in
+      let encoded = Sdnv.encode value in
+      match Sdnv.decode encoded 0 with
+      | Ok (decoded, _) ->
+          Alcotest.(check int64)
+            (Printf.sprintf "2^%d-1 roundtrips" n)
+            value decoded;
+          test_power (n + 1)
+      | Error _ -> Alcotest.fail (Printf.sprintf "decode failed for 2^%d-1" n)
+    end
+  in
+  test_power 1
+
+(* {1 Test Runner} *)
+
+let () =
+  Alcotest.run "sdnv"
+    [
+      ( "RFC 5326 vectors",
+        [
+          Alcotest.test_case "0x7F" `Quick test_rfc5326_0x7f;
+          Alcotest.test_case "0xABC" `Quick test_rfc5326_0xabc;
+          Alcotest.test_case "0x1234" `Quick test_rfc5326_0x1234;
+          Alcotest.test_case "0x4234" `Quick test_rfc5326_0x4234;
+        ] );
+      ( "boundary values",
+        [
+          Alcotest.test_case "zero" `Quick test_zero;
+          Alcotest.test_case "127 (max 1-byte)" `Quick test_boundary_127;
+          Alcotest.test_case "128 (first 2-byte)" `Quick test_boundary_128;
+          Alcotest.test_case "16383 (max 2-byte)" `Quick test_boundary_16383;
+          Alcotest.test_case "16384 (first 3-byte)" `Quick test_boundary_16384;
+        ] );
+      ( "large values",
+        [
+          Alcotest.test_case "0x123456789" `Quick test_large_value;
+          Alcotest.test_case "max int64" `Quick test_max_int63;
+        ] );
+      ( "errors",
+        [
+          Alcotest.test_case "truncated single" `Quick test_truncated;
+          Alcotest.test_case "truncated multi" `Quick test_truncated_multi;
+          Alcotest.test_case "negative rejected" `Quick test_negative_rejected;
+        ] );
+      ( "offset",
+        [
+          Alcotest.test_case "decode with offset" `Quick test_decode_with_offset;
+        ] );
+      ( "roundtrip",
+        [
+          Alcotest.test_case "powers of 2" `Quick test_roundtrip_powers_of_two;
+          Alcotest.test_case "powers of 2 minus 1" `Quick
+            test_roundtrip_powers_of_two_minus_one;
+        ] );
+    ]