Skip to main content
Version: 1.0.0

Configuration

This page covers Rust runtime configuration. Fory::builder().xlang(true).build() selects xlang mode with compatible schema evolution. Native mode is selected explicitly with .xlang(false) and defaults to schema-consistent payloads.

Wire Modes​

Apache Fory™ supports two serialization modes:

Xlang Mode​

Xlang mode is selected with .xlang(true) and uses the cross-language wire format. Compatible schema evolution is the xlang default and is recommended for cross-language services because schemas can diverge more easily across languages:

let fory = Fory::builder().xlang(true).build();

Use .compatible(false) only for xlang payloads where every peer updates the same schema together:

let fory = Fory::builder().xlang(true).compatible(false).build();

Native Mode​

For Rust-only payloads, native mode is explicit and schema-consistent by default:

let fory = Fory::builder().xlang(false).build();

Add .compatible(true) only when Rust-only deployments need schema evolution.

Configuration​

Maximum Dynamic Object Nesting Depth​

Apache Fory™ provides protection against stack overflow from deeply nested dynamic objects during deserialization. By default, the maximum nesting depth is set to 5 levels for trait objects and containers.

Default configuration:

let fory = Fory::builder().xlang(true).build(); // max_dyn_depth = 5

Custom depth limit:

let fory = Fory::builder().xlang(true).max_dyn_depth(10).build(); // Allow up to 10 levels

When to adjust:

  • Increase: For legitimate deeply nested data structures
  • Decrease: For stricter security requirements or shallow data structures

Protected types:

  • Box<dyn Any>, Rc<dyn Any>, Arc<dyn Any>
  • Box<dyn Trait>, Rc<dyn Trait>, Arc<dyn Trait> (trait objects)
  • RcWeak<T>, ArcWeak<T>
  • Collection types (Vec, HashMap, HashSet)
  • Nested struct types in Compatible mode

Note: Static data types (non-dynamic types) are secure by nature and not subject to depth limits, as their structure is known at compile time.

Explicit Xlang Examples​

Set .xlang(true) explicitly for xlang serialization examples:

let fory = Fory::builder().xlang(true).build();

Builder Pattern​

use fory::Fory;

// Default xlang configuration
let fory = Fory::builder().xlang(true).build();

// Native mode for Rust-only traffic
let fory = Fory::builder().xlang(false).build();

// Native mode with schema evolution
let fory = Fory::builder().xlang(false).compatible(true).build();

// Custom depth limit
let fory = Fory::builder().xlang(true).max_dyn_depth(10).build();

// Combined configuration
let fory = Fory::builder()
    .xlang(true)
    .compatible(true)
    .max_dyn_depth(10).build();

Configuration Summary​

OptionDescriptionDefault
compatible(bool)Enable schema evolutionxlang: true; native: false
xlang(bool)Use xlang modetrue
max_dyn_depth(u32)Maximum nesting depth for dynamic types5

Security​

Security-related configuration:

  • Register application structs and trait-object implementations before deserializing untrusted payloads.
  • Use max_dyn_depth(...) to reject unexpectedly deep dynamic object graphs.
  • Prefer concrete typed fields over dyn Any or broad trait-object fields for untrusted input.