mod.rs

Overview

This file provides functionality related to conditional misbehavior simulation, enabled via the misbehave feature flag. It defines data structures and a function to load misbehavior rules from a YAML configuration file, which can be used to simulate specific faulty behaviors in the system, particularly for testing purposes involving fork scenarios.

Data Structures

MisbehaveRules

A container struct representing the set of misbehavior rules loaded from configuration.

• Fields:

  • fork_test: ForkTest — Configuration for fork-related misbehavior.

• Derives:

  • Debug

  • Deserialize

  • Serialize

• Usage Example:

if let Ok(Some(rules)) = misbehave_rules() {
    println!("Loaded misbehavior rules: {:?}", rules);
}

ForkTest

Represents parameters defining a fork test interval, specifying the range of sequence numbers where the fork misbehavior applies.

• Fields:

  • from_seq: u32 — The starting sequence number of the fork test interval.

  • to_seq: u32 — The ending sequence number of the fork test interval.

• Derives:

  • Debug

  • Deserialize

  • Serialize

• Usage Example:

println!("Fork test from {} to {}", fork_test.from_seq, fork_test.to_seq);

Functions

misbehave_rules() -> anyhow::Result<Option<MisbehaveRules>>

Reads misbehavior rules from a YAML file specified by the environment variable MISBEHAVE_RULES_PATH. Returns an optional MisbehaveRules instance if the file is present and parsed successfully.

• Behavior:

  • Checks for the environment variable MISBEHAVE_RULES_PATH.

  • If set, opens the file at the path specified.

  • Reads the file contents into a string.

  • Parses the YAML string into a MisbehaveRules instance.

  • Returns Ok(Some(rules)) if successful.

  • Returns Ok(None) if environment variable is not set (misbehavior disabled).

  • Returns an error (anyhow::Error) if file reading or YAML parsing fails.

• Return:

  • Ok(Some(MisbehaveRules)) if rules are loaded.

  • Ok(None) if no rules are specified.

  • Err(anyhow::Error) if an error occurs during file read or parsing.

• Usage Example:

match misbehave_rules() {
    Ok(Some(rules)) => {
        // Apply misbehavior rules
    }
    Ok(None) => {
        // Misbehavior disabled
    }
    Err(e) => {
        eprintln!("Failed to load misbehavior rules: {}", e);
    }
}

Implementation Details

• The entire module is conditionally compiled only if the misbehave feature is enabled.

• Uses serde for serialization and deserialization of YAML configuration files.

• The misbehavior rules configuration is externalized to a YAML file, allowing dynamic modification without code changes.

• The ForkTest struct defines a sequence range that could be used by other parts of the system to simulate a fork occurring between sequence numbers.

Interaction with Other System Components

• This module relies on the environment variable MISBEHAVE_RULES_PATH to locate configuration files, thus interacting with the system environment.

• The loaded MisbehaveRules data is expected to be consumed by testing or simulation components that introduce misbehavior, particularly related to network or blockchain forks.

• The deserialized ForkTest struct likely interfaces with components that handle sequence tracking or consensus testing, enabling fault injection during specified sequence intervals.

Diagram: Module Structure and Workflow

flowchart TD
A["Start: misbehave_rules()"] --> B{MISBEHAVE_RULES_PATH set?}
B -- Yes --> C[Open file at path]
C --> D[Read file contents]
D --> E[Parse YAML into MisbehaveRules]
E --> F["Return Ok(Some(MisbehaveRules))"]
B -- No --> G["Return Ok(None)"]
C -->|Error| H[Return Err]
D -->|Error| H
E -->|Error| H

This flowchart illustrates the decision and processing flow within the misbehave_rules function, showing how the environment variable drives file reading and YAML parsing leading to loading or disabling misbehavior rules.