VCDIFF Dart Decoder

A Dart implementation of a VCDIFF (RFC 3284) decoder for efficient binary differencing and compression.

Overview

This library provides a VCDIFF decoder that can decode delta files created according to RFC 3284 - The VCDIFF Generic Differencing and Compression Data Format. VCDIFF is a format for expressing one data stream as a variant of another data stream, commonly used for binary differencing, compression, and patch applications.

Features

• RFC 3284 Compliant: Full implementation of the VCDIFF decoding specification including support for all VCDIFF instruction types (ADD, COPY, RUN)
• Address Caching: Efficient decoding with address cache implementation
• Checksum Validation: Adler-32 checksum validation support
• Robust Error Handling: Detailed error messages for debugging malformed files
• Extensive Testing: 85 test cases with reference test suite validation

Limitations

• Application Headers: This implementation does not handle application header information
• Secondary Compression: This decoder does not support secondary compression (eg, gzip, bzip2)
• Custom Code Tables: This decoder does not support custom instruction code tables
• Compatibility: Works with VCDIFF deltas created using xdelta3 -e -S -A (no secondary compression, no application header)

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  vcdiff_decoder: ^0.1.0

Usage

Basic Decoding

import 'dart:io';
import 'package:vcdiff_decoder/vcdiff_decoder.dart';

void main() {
  // Read the source file
  final source = File('original.txt').readAsBytesSync();

  // Read the VCDIFF delta file
  final delta = File('changes.vcdiff').readAsBytesSync();

  // Decode the delta to reconstruct the target
  final target = decode(source, delta);

  // Write the result
  File('result.txt').writeAsBytesSync(target);
}

Reusable Decoder

For decoding multiple deltas against the same source:

import 'dart:io';
import 'package:vcdiff_decoder/vcdiff_decoder.dart';

void main() {
  final source = File('original.txt').readAsBytesSync();
  final decoder = Decoder(source);

  // Decode multiple deltas
  final target1 = decoder.decode(File('delta1.vcdiff').readAsBytesSync());
  final target2 = decoder.decode(File('delta2.vcdiff').readAsBytesSync());
}

Error Handling

The decoder provides specific exception types for different error conditions:

import 'package:vcdiff_decoder/vcdiff_decoder.dart';

void main() {
  try {
    final target = decode(source, delta);
  } on InvalidMagicException catch (e) {
    print('Invalid VCDIFF file: $e');
  } on InvalidVersionException catch (e) {
    print('Unsupported VCDIFF version: $e');
  } on InvalidChecksumException catch (e) {
    print('Checksum validation failed: $e');
  } on VcdiffException catch (e) {
    print('VCDIFF error: $e');
  }
}

API Reference

Core Functions

decode(Uint8List source, Uint8List delta) → Uint8List

Decodes a VCDIFF delta file using the provided source data and returns the reconstructed target data.

Parameters:

• source: The original source data (may be empty for deltas that don't reference source)
• delta: The VCDIFF delta file data

Returns:

• Decoded target data as Uint8List

Throws:

• VcdiffException if decoding fails (malformed delta, checksum validation failure, etc.)

Decoder(Uint8List source)

Creates a new decoder instance with the specified source data. Useful for decoding multiple deltas against the same source.

Parameters:

• source: The source data for decoding operations

Methods:

• decode(Uint8List delta) → Uint8List: Decodes a single VCDIFF delta using the decoder's source data

Exception Types

• VcdiffException: Base exception for all VCDIFF errors
• InvalidMagicException: Invalid VCDIFF magic bytes
• InvalidVersionException: Unsupported VCDIFF version
• InvalidFormatException: Invalid VCDIFF format
• CorruptedDataException: Corrupted VCDIFF data
• InvalidChecksumException: Checksum validation failure

Checksum Support

• VCD_ADLER32: This implementation detects and parses the VCD_ADLER32 extension (bit 0x04 in window indicator)
• Non-standard Extension: The Adler-32 checksum is not part of RFC 3284 but is supported by some implementations
• Validation: Full Adler-32 checksum validation is implemented and performed during decoding

Testing

This implementation has been tested via a combination of the tests in https://github.com/ably/vcdiff-tests plus fuzz tests.See FUZZING.md for detailed fuzzing documentation.

Run tests:

# Run all tests (integration + fuzz)
dart test

# Run only integration tests
dart test test/vcdiff_test.dart

# Run only fuzz tests
dart test test/fuzz_test.dart

Creating VCDIFF Deltas

This is a decoder-only library. To create compatible VCDIFF delta files, use tools such as xdelta3:

# Create a VCDIFF delta (compatible with this decoder)
xdelta3 -e -S -A -s original.txt modified.txt delta.vcdiff

# Decode using this library
dart run your_script.dart

License

This project is licensed under the Apache 2 License.

References

• RFC 3284: The VCDIFF Generic Differencing and Compression Data Format
• xdelta3: VCDIFF binary diff tool
• VCDIFF Test Suite

Contributing

Contributions are welcomed. See CONTRIBUTING.md for full guidelines on setting up a development environment, coding standards, and the pull request process.