Struct Builder 

pub struct Builder { /* private fields */ }

The main DDEX Builder for creating deterministic XML output.

Builder is the primary interface for generating DDEX-compliant XML with guaranteed deterministic output. It supports partner presets, version conversion, and comprehensive security features.

Features

• Deterministic Output: Uses DB-C14N/1.0 for byte-perfect reproducibility
• Partner Presets: Pre-configured settings for major music platforms
• Version Management: Support for ERN 3.8.2, 4.2, and 4.3 with conversion
• Security: Built-in validation, rate limiting, and XXE protection
• Performance: Memory-optimized with streaming support for large files

Usage Patterns

Basic Usage

use ddex_builder::Builder;

let builder = Builder::new();
let available_presets = builder.available_presets();
println!("Available presets: {:?}", available_presets);

With Partner Preset

use ddex_builder::Builder;

let mut builder = Builder::new();
builder.preset("spotify_audio_43")?;
 
// Builder is now configured for Spotify Audio releases (ERN 4.3)
assert!(builder.is_preset_locked() == false); // Unlocked for further customization

Locked Preset Configuration

use ddex_builder::Builder;

let mut builder = Builder::new();
builder.apply_preset("spotify_audio_43", true)?; // Lock the preset
 
assert!(builder.is_preset_locked());

Version Conversion

use ddex_builder::{Builder, DdexVersion};
use ddex_builder::versions::ConversionOptions;

let builder = Builder::new();
 
// Check version compatibility
let compatible = builder.is_version_compatible(
    DdexVersion::Ern382, 
    DdexVersion::Ern43
);
 
if compatible {
    let options = Some(ConversionOptions::default());
    let result = builder.convert_version(
        &xml_content,
        DdexVersion::Ern382,
        DdexVersion::Ern43,
        options
    )?;
    println!("Converted XML: {}", result.converted_xml);
}

Thread Safety

Builder is Send + Sync and can be safely shared between threads. Each thread should create its own instance for best performance.

Memory Usage

The builder uses memory-optimized data structures and streaming where possible. Typical memory usage:

• Small releases (<100KB): ~5MB
• Large releases (>1MB): ~20-50MB with streaming

Implementations

impl Builder

pub fn new() -> Self

Creates a new DDEX Builder with default configuration.

The builder is initialized with:

• Default determinism configuration for byte-perfect output
• All available partner presets loaded
• No preset locked (can be changed)
• Latest supported DDEX version as target

Examples

use ddex_builder::Builder;

let builder = Builder::new();
assert!(!builder.is_preset_locked());
assert!(builder.available_presets().len() > 0);

Performance

Creating a new builder is fast (~1μs) as presets are loaded from embedded configuration data.

pub fn with_config(config: DeterminismConfig) -> Self

Create builder with custom configuration

pub fn with_perfect_fidelity() -> Self

Create builder with Perfect Fidelity Engine enabled

pub fn with_fidelity_options(fidelity_options: FidelityOptions) -> Self

Create builder with custom fidelity options

pub fn for_round_trip() -> Self

Create builder optimized for round-trip operations

pub fn apply_preset( &mut self, preset_name: &str, lock: bool, ) -> Result<(), BuildError>

Applies a partner preset configuration to the builder.

Presets contain pre-configured settings optimized for specific music platforms and distribution partners. Each preset includes determinism settings, validation rules, and format preferences.

Arguments

• preset_name - Name of the preset to apply (see available_presets)
• lock - Whether to lock the preset to prevent further modifications

Returns

• Ok(()) - Preset applied successfully
• Err(BuildError::InvalidFormat) - Unknown preset name

Examples

use ddex_builder::Builder;

let mut builder = Builder::new();

// Apply Spotify preset without locking
builder.apply_preset("spotify_audio_43", false)?;
assert!(!builder.is_preset_locked());

// Apply and lock YouTube preset  
builder.apply_preset("youtube_video_43", true)?;
assert!(builder.is_preset_locked());

Available Presets

Common presets include:

• spotify_audio_43 - Spotify audio releases (ERN 4.3)
• youtube_video_43 - YouTube video content (ERN 4.3)
• apple_music_43 - Apple Music releases (ERN 4.3)
• universal_basic - Universal Music basic preset
• sony_enhanced - Sony Music enhanced features

Use available_presets to get the complete list.

pub fn preset(&mut self, preset_name: &str) -> Result<&mut Self, BuildError>

Apply a preset configuration (alias for apply_preset for convenience)

pub fn available_presets(&self) -> Vec<String>

Get available preset names

pub fn get_preset(&self, preset_name: &str) -> Option<&PartnerPreset>

Get preset details

pub fn is_preset_locked(&self) -> bool

Check if a preset is locked

pub fn config(&self) -> &DeterminismConfig

Get the current configuration

pub fn fidelity_options(&self) -> &FidelityOptions

Get the current fidelity options

pub fn set_fidelity_options(&mut self, options: FidelityOptions) -> &mut Self

Set fidelity options

pub fn enable_perfect_fidelity(&mut self) -> &mut Self

Enable Perfect Fidelity Engine with default settings

pub fn disable_perfect_fidelity(&mut self) -> &mut Self

Disable Perfect Fidelity Engine

pub fn with_canonicalization( &mut self, algorithm: CanonicalizationAlgorithm, ) -> &mut Self

Set canonicalization algorithm

pub fn with_db_c14n(&mut self) -> &mut Self

Enable DB-C14N/1.0 canonicalization (default for DDEX)

pub fn with_c14n(&mut self) -> &mut Self

Enable standard XML C14N canonicalization

pub fn with_c14n11(&mut self) -> &mut Self

Enable XML C14N 1.1 canonicalization

pub fn with_custom_canonicalization( &mut self, rules: CustomCanonicalizationRules, ) -> &mut Self

Set custom canonicalization rules

pub fn with_verification(&mut self, config: VerificationConfig) -> &mut Self

Enable build verification

pub fn with_statistics(&mut self) -> &mut Self

Enable statistics collection

pub fn is_perfect_fidelity_enabled(&self) -> bool

Check if Perfect Fidelity Engine is enabled

pub fn canonicalization_algorithm(&self) -> &CanonicalizationAlgorithm

Get current canonicalization algorithm

pub fn with_version(&mut self, version: DdexVersion) -> &mut Self

Set target DDEX version for building

pub fn target_version(&self) -> Option<DdexVersion>

Get the target DDEX version

pub fn detect_version( &self, xml_content: &str, ) -> Result<DdexVersion, BuildError>

Detect version from XML content

pub fn convert_version( &self, xml_content: &str, from_version: DdexVersion, to_version: DdexVersion, options: Option<ConversionOptions>, ) -> Result<ConverterResult, BuildError>

Convert XML between DDEX versions

pub fn is_version_compatible(&self, from: DdexVersion, to: DdexVersion) -> bool

Get version compatibility information

pub fn supported_versions(&self) -> Vec<DdexVersion>

Get supported DDEX versions

pub fn build_with_fidelity( &self, request: &BuildRequest, ) -> Result<FidelityBuildResult, BuildError>

Build DDEX XML with Perfect Fidelity Engine

pub fn verify_build( &self, xml_output: &str, ) -> Result<VerificationResult, BuildError>

Verify build output meets fidelity requirements

pub fn test_round_trip_fidelity( &self, original_xml: &str, ) -> Result<RoundTripResult, BuildError>

Test round-trip fidelity: XML → Parse → Build → Parse → Compare

pub fn canonicalize(&self, xml_content: &str) -> Result<String, BuildError>

Canonicalize XML using the configured algorithm

pub fn db_c14n_config(&self) -> DbC14NConfig

Get DB-C14N/1.0 configuration details

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Builder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Self

Returns the “default value” for a type.