Crate hedl_xml 

HEDL XML Conversion

Provides bidirectional conversion between HEDL documents and XML format.

Features

• Convert HEDL documents to well-formed XML
• Parse XML into HEDL documents with type inference
• Streaming support for large multi-gigabyte XML files
• Async I/O with Tokio (via async feature flag)
• XSD schema validation with comprehensive error messages
• Schema caching for high-performance validation
• Configurable output formatting (pretty print, attributes)
• Support for nested structures and matrix lists
• Reference and expression preservation

Security

XML External Entity (XXE) Prevention

The hedl-xml crate is protected against XXE attacks by default through multiple layers:

Layer 1: Safe Parser (quick-xml)

The underlying quick-xml library does not:

• Resolve external entities (file://, http://, etc.)
• Process DTD entity declarations
• Expand entity references defined in DOCTYPEs
• Support XInclude directives

This makes XXE attacks impossible regardless of configuration.

Layer 2: Entity Policy Controls

For defense-in-depth and compliance requirements, explicit entity policies are available:

use hedl_xml::{FromXmlConfig, EntityPolicy};

// Strictest: Reject any XML with DOCTYPE declarations
let strict_config = FromXmlConfig::strict_security();

// Default: Allow DOCTYPE but never resolve entities
let default_config = FromXmlConfig::default(); // AllowDtdNoExternal

// Monitoring: Warn on DTD/entity detection
let warn_config = FromXmlConfig {
    entity_policy: EntityPolicy::WarnOnEntities,
    log_security_events: true,
    ..Default::default()
};

XXE Attack Vectors (Mitigated)

The following XXE attack patterns are prevented:

• File Disclosure: <!ENTITY xxe SYSTEM "file:///etc/passwd"> - Not expanded
• Server-Side Request Forgery: External HTTP entities are not resolved
• Billion Laughs DoS: Entity definitions are ignored; no expansion occurs
• Out-of-Band Exfiltration: Parameter entities are not resolved or executed

Examples

Converting HEDL to XML

use hedl_core::{Document, Item, Value};
use hedl_xml::{to_xml, ToXmlConfig};
use std::collections::BTreeMap;

let mut doc = Document::new((2, 0));
doc.root.insert("name".to_string(), Item::Scalar(Value::String("example".to_string().into())));

let config = ToXmlConfig::default();
let xml = to_xml(&doc, &config).unwrap();

Converting XML to HEDL

use hedl_xml::{from_xml, FromXmlConfig};

let xml = r#"<?xml version="1.0"?><hedl><name>example</name></hedl>"#;
let config = FromXmlConfig::default();
let doc = from_xml(xml, &config).unwrap();

Streaming large XML files

For multi-gigabyte XML files, use the streaming API to process items incrementally without loading the entire document into memory:

use hedl_xml::streaming::{from_xml_stream, StreamConfig};
use std::fs::File;

let file = File::open("large.xml")?;
let config = StreamConfig::default();

for result in from_xml_stream(file, &config)? {
    match result {
        Ok(item) => println!("Processing: {}", item.key),
        Err(e) => eprintln!("Error: {}", e),
    }
}

XSD Schema Validation

Validate XML documents against XSD schemas:

use hedl_xml::schema::SchemaValidator;

let schema = r#"<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="person">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="age" type="xs:integer"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>"#;

let validator = SchemaValidator::from_xsd(schema)?;

let xml = r#"<?xml version="1.0"?>
<person>
  <name>Alice</name>
  <age>30</age>
</person>"#;

validator.validate(xml)?;

Async I/O (with async feature)

Enable async support in Cargo.toml:

[dependencies]
hedl-xml = { version = "*", features = ["async"] }
tokio = { version = "1", features = ["full"] }

Then use async functions:

use hedl_xml::async_api::{from_xml_file_async, to_xml_file_async};
use hedl_xml::{FromXmlConfig, ToXmlConfig};

// Read XML asynchronously
let doc = from_xml_file_async("input.xml", &FromXmlConfig::default()).await?;

// Process document...

// Write XML asynchronously
to_xml_file_async(&doc, "output.xml", &ToXmlConfig::default()).await?;

Re-exports

pub use schema::SchemaCache;

pub use schema::SchemaValidator;

pub use schema::ValidationError;

pub use security::SecurityViolation;

pub use security::XmlSecurityValidator;

pub use streaming::from_xml_stream;

pub use streaming::StreamConfig;

pub use streaming::StreamItem;

pub use streaming::XmlStreamingParser;

Modules

async_api

Async XML API. Async API for XML conversion with Tokio

schema

XML schema support. XSD Schema Validation for XML Documents

security

XML security validation. Security validation for XML processing

streaming

Streaming XML parsing. Streaming XML parser for handling large documents

Structs

FromXmlConfig

Configuration for XML import

ToXmlConfig

Configuration for XML output

Enums

EntityPolicy

Policy for handling XML entities and DTDs

Functions

from_xml

Convert XML string to HEDL Document

hedl_to_xml

Convert HEDL document to XML string with default configuration

to_xml

Convert HEDL Document to XML string

xml_to_hedl

Convert XML string to HEDL document with default configuration