Struct EvaluationConfig 

#[non_exhaustive]
pub struct EvaluationConfig {
    pub max_recursion_depth: u32,
    pub max_string_length: usize,
    pub stop_at_first_match: bool,
    pub enable_mime_types: bool,
    pub timeout_ms: Option<u64>,
}

Configuration for rule evaluation

This struct controls various aspects of magic rule evaluation behavior, including performance limits, output options, and matching strategies.

Forward compatibility

This struct is marked #[non_exhaustive]: new configuration fields may be added in any release without it being a breaking change. Construct instances via one of the factory constructors (EvaluationConfig::default(), EvaluationConfig::new(), EvaluationConfig::performance(), EvaluationConfig::comprehensive()) and then chain with_* builder-style setters:

use libmagic_rs::EvaluationConfig;

let custom_config = EvaluationConfig::default()
    .with_max_recursion_depth(10)
    .with_timeout_ms(Some(5_000));

Direct struct-literal construction (EvaluationConfig { .. }) is rejected by the compiler from outside this crate because of #[non_exhaustive].

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

max_recursion_depth: u32

Maximum recursion depth for nested rules

This prevents infinite recursion in malformed magic files and limits the depth of rule hierarchy traversal. Default is 20.

max_string_length: usize

Maximum string length to read

This limits the amount of data read for string types to prevent excessive memory usage. Default is 8192 bytes.

stop_at_first_match: bool

Stop at first match or continue for all matches

When true, evaluation stops after the first matching rule. When false, all rules are evaluated to find all matches. Default is true for performance.

Semantics

“First match” refers to the first top-level rule that matches. Children of the first matching top-level rule are always evaluated before the stop check; the stop check applies to subsequent top-level rules. In other words, stop_at_first_match = true does not truncate the child subtree of the matching rule – it only prevents later sibling top-level rules from being evaluated. A successful top-level match therefore returns one parent RuleMatch plus any descendant RuleMatch values its children produced.

enable_mime_types: bool

Enable MIME type mapping in results

When true, the evaluator will attempt to map file type descriptions to standard MIME types. Default is false.

timeout_ms: Option<u64>

Timeout for evaluation in milliseconds

If set, evaluation will be aborted if it takes longer than this duration. None means no timeout. Default is None.

Implementations

impl EvaluationConfig

pub fn new() -> Self

Create a new configuration with default values

Examples

use libmagic_rs::EvaluationConfig;

let config = EvaluationConfig::new();
assert_eq!(config.max_recursion_depth, 20);
assert_eq!(config.max_string_length, 8192);
assert!(config.stop_at_first_match);
assert!(!config.enable_mime_types);
assert_eq!(config.timeout_ms, None);

pub const fn performance() -> Self

Create a configuration optimized for performance

This configuration prioritizes speed over completeness:

• Lower recursion depth limit
• Smaller string length limit
• Stop at first match
• No MIME type mapping
• Short timeout

Examples

use libmagic_rs::EvaluationConfig;

let config = EvaluationConfig::performance();
assert_eq!(config.max_recursion_depth, 10);
assert_eq!(config.max_string_length, 1024);
assert!(config.stop_at_first_match);
assert!(!config.enable_mime_types);
assert_eq!(config.timeout_ms, Some(1000));

pub const fn comprehensive() -> Self

Create a configuration optimized for completeness

This configuration prioritizes finding all matches over speed:

• Higher recursion depth limit
• Larger string length limit
• Find all matches
• Enable MIME type mapping
• Longer timeout

Examples

use libmagic_rs::EvaluationConfig;

let config = EvaluationConfig::comprehensive();
assert_eq!(config.max_recursion_depth, 50);
assert_eq!(config.max_string_length, 32768);
assert!(!config.stop_at_first_match);
assert!(config.enable_mime_types);
assert_eq!(config.timeout_ms, Some(30000));

pub const fn with_max_recursion_depth(self, depth: u32) -> Self

Sets the maximum recursion depth for nested rule evaluation.

Builder-style setter for consumers outside this crate. Direct struct-literal construction is blocked by #[non_exhaustive], so chain with_* calls after one of the factory constructors (default, performance, comprehensive, new).

pub const fn with_max_string_length(self, length: usize) -> Self

Sets the maximum string length (in bytes) read for string types.

pub const fn with_stop_at_first_match(self, stop: bool) -> Self

Sets whether evaluation stops after the first top-level match.

pub const fn with_mime_types(self, enable: bool) -> Self

Enables or disables MIME type mapping in results.

pub const fn with_timeout_ms(self, timeout_ms: Option<u64>) -> Self

Sets the evaluation timeout in milliseconds. Pass None for unbounded evaluation (not recommended on untrusted input).

pub fn validate(&self) -> Result<()>

Validate the configuration settings

Performs comprehensive security validation of all configuration values to prevent malicious configurations that could lead to resource exhaustion, denial of service, or other security issues.

Security

This validation prevents:

• Stack overflow attacks through excessive recursion depth
• Memory exhaustion through oversized string limits
• Denial of service through excessive timeouts
• Integer overflow in configuration calculations

Errors

Returns LibmagicError::ConfigError if any configuration values are invalid or out of reasonable bounds.

Examples

use libmagic_rs::EvaluationConfig;

let config = EvaluationConfig::default();
assert!(config.validate().is_ok());

let invalid_config = EvaluationConfig::default().with_max_recursion_depth(0);
assert!(invalid_config.validate().is_err());

Trait Implementations

impl Clone for EvaluationConfig

fn clone(&self) -> EvaluationConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for EvaluationConfig

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

Formats the value using the given formatter.

impl Default for EvaluationConfig

fn default() -> Self

Returns the default evaluation configuration.

Security

The default configuration has no timeout. When processing untrusted input, use EvaluationConfig::performance() or set timeout_ms explicitly to prevent denial of service.

impl PartialEq for EvaluationConfig

fn eq(&self, other: &EvaluationConfig) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for EvaluationConfig

impl StructuralPartialEq for EvaluationConfig