Crate ddex_builder

Expand description

§DDEX Builder - Deterministic DDEX XML Generation

A high-performance, memory-safe DDEX XML builder that generates deterministic, byte-perfect XML using DB-C14N/1.0 canonicalization. Built in Rust with comprehensive security features and bindings for JavaScript, Python, and WebAssembly.

§Key Features

🔒 Security First: XXE protection, input validation, rate limiting, and comprehensive security measures
⚡ High Performance: Sub-millisecond generation for typical releases, memory-optimized streaming
🎯 Deterministic Output: Guaranteed byte-perfect reproducibility using DB-C14N/1.0
🔄 Round-trip Fidelity: Perfect compatibility with ddex-parser for Parse → Build → Parse workflows
🛠️ Partner Presets: Pre-configured settings for Spotify, YouTube, Apple Music, and other platforms
🌐 Multi-platform: Native Rust, Node.js, Python, and WebAssembly bindings
📊 Version Support: Full support for ERN 3.8.2, 4.2, 4.3 with automatic conversion

§Quick Start

use ddex_builder::{Builder, DdexVersion};
use ddex_builder::builder::{BuildRequest, OutputFormat};

// Create a builder with Spotify preset
let mut builder = Builder::new();
builder.preset("spotify_audio_43")?;

// Build DDEX XML
let request = BuildRequest {
    source_xml: r#"<SoundRecording>...</SoundRecording>"#.to_string(),
    output_format: OutputFormat::Xml,
    preset: Some("spotify_audio_43".to_string()),
    validate_schema: true,
};

let result = builder.build_internal(&request)?;
println!("Generated DDEX XML: {}", result.xml);

§Security Features

DDEX Builder includes comprehensive security measures:

use ddex_builder::{InputValidator, SecurityConfig, ApiSecurityManager};

// Configure security settings
let security_config = SecurityConfig {
    max_xml_size: 10_000_000,        // 10MB limit
    max_json_depth: 32,              // Prevent deep nesting attacks
    rate_limiting_enabled: true,
    max_requests_per_minute: 100,
    validate_urls: true,
    block_private_ips: true,
    ..Default::default()
};

// Validate inputs
let validator = InputValidator::new(security_config.clone());
validator.validate_xml_content(&xml_input)?;

// API security management
let mut api_security = ApiSecurityManager::new(security_config);
api_security.validate_request("build", "client_id", xml_input.len())?;

§Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        DDEX Builder                             │
├─────────────────────────────────────────────────────────────────┤
│  Input Layer                                                    │
│  ┌─────────────┐ ┌──────────────┐ ┌─────────────┐              │
│  │ XML Parser  │ │ JSON Parser  │ │ Presets     │              │
│  │ (Security)  │ │ (Validation) │ │ (Partners)  │              │
│  └─────────────┘ └──────────────┘ └─────────────┘              │
├─────────────────────────────────────────────────────────────────┤
│  Processing Layer                                               │
│  ┌─────────────┐ ┌──────────────┐ ┌─────────────┐              │
│  │ AST Builder │ │ Reference    │ │ Version     │              │
│  │ (Elements)  │ │ Linker       │ │ Converter   │              │
│  └─────────────┘ └──────────────┘ └─────────────┘              │
├─────────────────────────────────────────────────────────────────┤
│  Output Layer                                                   │
│  ┌─────────────┐ ┌──────────────┐ ┌─────────────┐              │
│  │ XML         │ │ DB-C14N      │ │ Output      │              │
│  │ Generator   │ │ Canonicalize │ │ Sanitizer   │              │
│  └─────────────┘ └──────────────┘ └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘

§Performance Characteristics

Parse 10KB: <5ms
Parse 100KB: <10ms
Parse 1MB: <50ms
Build typical release: <15ms
Memory usage: <50MB for large files with streaming
WASM bundle size: <500KB

§Version Support

DDEX Version	Support Level	Notes
ERN 3.8.2	✅ Full	Legacy support
ERN 4.2	✅ Full	Enhanced features
ERN 4.3	✅ Full	Latest standard

§Partner Presets

Pre-configured settings for major platforms:

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

See the User Guide for detailed preset documentation.

Re-exports§

pub use builder::DDEXBuilder;
pub use builder::BuildOptions;
pub use builder::BuildRequest;
pub use builder::BuildResult;
pub use canonical::DB_C14N;
pub use determinism::DeterminismConfig;
pub use error::BuildError;
pub use error::BuildWarning;
pub use guarantees::DeterminismGuarantee;
pub use guarantees::DeterminismGuaranteeValidator;
pub use guarantees::GuaranteeReport;
pub use presets::PartnerPreset;
pub use linker::ReferenceLinker;
pub use linker::LinkerConfig;
pub use linker::EntityType;
pub use linker::LinkerError;
pub use id_generator::StableHashGenerator;
pub use id_generator::StableHashConfig;
pub use id_generator::HashAlgorithm;
pub use preflight::PreflightValidator;
pub use preflight::ValidationConfig;
pub use preflight::ValidationResult;
pub use preflight::PreflightLevel;
pub use diff::DiffEngine;
pub use diff::DiffConfig;
pub use diff::VersionCompatibility;
pub use diff::types::ChangeSet;
pub use diff::types::SemanticChange;
pub use diff::types::DiffPath;
pub use diff::types::ChangeType;
pub use diff::types::ImpactLevel;
pub use diff::formatter::DiffFormatter;
pub use messages::UpdateReleaseMessage;
pub use messages::UpdateGenerator;
pub use messages::UpdateAction;
pub use messages::UpdateConfig;
pub use messages::ValidationStatus;
pub use schema::SchemaGenerator;
pub use schema::JsonSchema;
pub use schema::SchemaConfig;
pub use schema::SchemaDraft;
pub use schema::SchemaCommand;
pub use versions::VersionManager;
pub use versions::VersionConverter;
pub use versions::ConverterResult as ConversionResult;
pub use versions::ConversionOptions;
pub use presets::DdexVersion;
pub use security::InputValidator;
pub use security::SecurityConfig;
pub use security::RateLimiter;
pub use security::SecureTempFile;
pub use security::OutputSanitizer;
pub use api_security::ApiSecurityManager;
pub use api_security::ApiSecurityConfig;
pub use api_security::FfiDataType;
pub use api_security::BatchStats;
pub use fidelity::FidelityConfig;
pub use fidelity::PreservationLevel;
pub use fidelity::FidelityStatistics;
pub use verification::BuildVerifier;
pub use verification::VerificationStatistics;
pub use round_trip::RoundTripTester;
pub use round_trip::FidelityAnalysis;

Modules§

api_security: API Security Features for DDEX Builder
ast: Abstract Syntax Tree for DDEX XML generation
builder: Main builder implementation
caching: Caching optimizations for DDEX Builder
canonical: DB-C14N/1.0 - DDEX Builder Canonicalization
determinism: Determinism Configuration and Enforcement
diff: Semantic diff engine for DDEX messages
error: Error types for DDEX Builder
fidelity: Perfect Fidelity Engine for DDEX Builder
generator: AST Generation Engine
guarantees: Determinism guarantees and validation for DDEX Builder
id_generator: Stable hash-based ID generation for deterministic DDEX messages
linker: Reference linker for automatic ID generation and relationship management
memory_optimization: Memory optimization techniques for DDEX Builder
messages: DDEX Message Types
namespace_minimizer: Namespace Minimizer for DDEX Builder
optimized_strings: Optimized string handling for DDEX Builder performance
parallel_processing: Parallel processing optimizations for DDEX Builder
preflight: Comprehensive preflight validation for DDEX messages
presets: DDEX Configuration Presets
round_trip: Round-trip testing for Perfect Fidelity Engine
schema: JSON Schema Generation for DDEX Models
security: Security module for DDEX Builder
streaming: Streaming DDEX XML builder for large catalogs
verification: Build Verification for Perfect Fidelity Engine
versions: Multi-version DDEX support and conversion

Structs§

BuildStatistics: Building statistics collected during the build process
Builder: The main DDEX Builder for creating deterministic XML output.
CustomCanonicalizationRules: Custom canonicalization rules for specialized use cases
DbC14NConfig: DB-C14N/1.0 configuration
FidelityBuildResult: Perfect Fidelity Engine build result
FidelityOptions: Perfect Fidelity Engine configuration options
RoundTripResult: Round-trip test result
VerificationConfig: Build verification configuration
VerificationIssue: Verification issue (error or warning)
VerificationResult: Build verification result

Enums§

CanonicalizationAlgorithm: Canonicalization algorithms supported by the Perfect Fidelity Engine
NamespaceHandling: Namespace handling strategies
VerificationSeverity: Verification issue severity

Constants§

DB_C14N_VERSION: Version of the DB-C14N specification

Functions§

fidelity_engine_info: Get Perfect Fidelity Engine information
version_info: Version information for the builder

Crate ddex_builder

Crate ddex_builder Copy item path

§DDEX Builder - Deterministic DDEX XML Generation

§Key Features

§Quick Start

§Security Features

§Architecture Overview

§Performance Characteristics

§Version Support

§Partner Presets

Re-exports§

Modules§

Structs§

Enums§

Constants§

Functions§

Crate ddex_builder