vcdiff#

VCDIFF (RFC 3284) binary delta encoding in pure OCaml.

Overview#

VCDIFF is the IETF's generic differencing format: a delta file encodes a target byte string as ADD / RUN / COPY instructions over a source byte string. It is the wire format produced by xdelta3 and used by HTTP delta encoding (RFC 3229).

• diff -- compute a delta with a greedy block-hash matcher
• apply -- reconstruct the target, including overlapping (self-growing) copies, VCD_TARGET windows and Adler-32 window checksums
• of_string / to_string -- decode a delta to a value (windows of typed instructions, COPY address caches resolved) and re-encode it

The decoder accepts any delta that uses the default instruction code table, including the xdelta3 application-header (VCD_APPHEADER) and window checksum (VCD_ADLER32) extensions. Secondary compression and application-defined code tables are rejected with a typed Unsupported error.

Installation#

$ opam install vcdiff

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install vcdiff

Usage#

# let source = "the quick brown fox jumps over the lazy dog" in
  let target = "the quick brown cat jumps over the lazy dog!" in
  let delta = Vcdiff.diff ~source ~target in
  Vcdiff.apply_exn ~source delta = target
- : bool = true

A delta of similar inputs is much smaller than the target it reconstructs:

# let source = String.init 4096 (fun i -> Char.chr (i land 0xff)) in
  let target = String.sub source 7 4000 ^ "tail" in
  let delta = Vcdiff.to_string (Vcdiff.diff ~source ~target) in
  String.length delta < 64
- : bool = true

Deltas are ordinary values, so they can be inspected and built directly:

# let w =
    {
      Vcdiff.Value.Window.source = None;
      checksum = None;
      insts =
        [ Vcdiff.Value.Add "ab"; Vcdiff.Value.Copy { addr = 0; len = 6 } ];
    }
  in
  Vcdiff.apply_exn ~source:"" { Vcdiff.Value.app_header = None; windows = [ w ] }
- : string = "abababab"

License#

ISC -- see LICENSE.md.