Module dfir_rs::util::simulation

source ·
Expand description

§Hydroflow Deterministic Simulation Testing Framework

This module provides a deterministic simulation testing framework for testing Hydroflow processes.

It can be used to test complex interactions between multiple Hydroflow processes in a deterministic manner by running them in a single-threaded environment. The framework also provides a “virtual network” implementation that allows production processes to exchange messages within the simulation. More importantly, the network is fully under control of the unit test and the test can introduce faults such as message delays, message drops and network partitions.

§Overview

Conceptually, the simulation contains a “Fleet”, which is a collection of “Hosts”. These aren’t real hosts, but rather a collection of individual Hydroflow processes (one per host) that can communicate with each other over a virtual network. Every host has a “hostname” which uniquely identifies it within the fleet.

 ┌───────────────────────────────────────────────────────────────────────────────────────────┐
 │SIMULATION                                                                                 │
 │ ┌───────────────────────────────────────────────────────────────────────────────────────┐ │
 │ │FLEET                                                                                  │ │
 │ │ ┌───────────────────────────────┐                   ┌───────────────────────────────┐ │ │
 │ │ │HOST                           │                   │HOST                           │ │ │
 │ │ │ ┌──────┐   ┌──────┐  ┌──────┐ │                   │ ┌──────┐   ┌──────┐  ┌──────┐ │ │ │
 │ │ │ │INBOX │   │INBOX │  │INBOX │ │                 ┌-┼-►INBOX │   │INBOX │  │INBOX │ │ │ │
 │ │ │ └──┬───┘   └──┬───┘  └──┬───┘ │                 │ │ └──┬───┘   └──┬───┘  └──┬───┘ │ │ │
 │ │ │ ┌──▼──────────▼─────────▼───┐ │                 │ │ ┌──▼──────────▼─────────▼───┐ │ │ │
 │ │ │ │                           │ │                 │ │ │                           │ │ │ │
 │ │ │ │        TRANSDUCER         │ │                 │ │ │        TRANSDUCER         │ │ │ │
 │ │ │ │                           │ │                 │ │ │                           │ │ │ │
 │ │ │ └───┬─────────┬──────────┬──┘ │                 │ │ └───┬─────────┬─────────┬───┘ │ │ │
 │ │ │  ┌──▼───┐  ┌──▼───┐  ┌───▼──┐ │                 │ │  ┌──▼───┐  ┌──▼───┐  ┌──▼───┐ │ │ │
 │ │ │  │OUTBOX│  │OUTBOX│  │OUTBOX┼-┼--┐              │ │  │OUTBOX│  │OUTBOX│  │OUTBOX│ │ │ │
 │ │ │  └──────┘  └──────┘  └──────┘ │  │              │ │  └──────┘  └──────┘  └──────┘ │ │ │
 │ │ └───────────────────────────────┘  │              │ └───────────────────────────────┘ │ │
 │ └────────────────────────────────────┼──────────────┼───────────────────────────────────┘ │
 │                                    ┌─┼──────────────┼─┐                                   │
 │                                    │ └--------------┘ │                                   │
 │                                    │ NETWORK MESSAGE  │                                   │
 │                                    │    PROCESSING    │                                   │
 │                                    └──────────────────┘                                   │
 └───────────────────────────────────────────────────────────────────────────────────────────┘

§Network Processing

§Outboxes & Inboxes

When a process wishes to send a message to another process, it sends the message to an “outbox” on its host. The unit test invokes the simulation’s network message processing logic at some desired cadence to pick up all messages from all outboxes and deliver them to the corresponding inboxes on the destination hosts. The network message processing logic is the point at which failures can be injected to change the behavior of the network.

§Interface Names

Every inbox and outbox is associated with an “interface name”. This is a string that uniquely identifies the interface on the host. When a process sends a message, it specifies the destination hostname and the interface name on that host to which the message should be delivered.

§Progress of Time in the Simulation

The single-threaded unit test can drive time forward on every host by invoking the run_tick method on the host. This ultimately runs a single tick on the process. The unit test is also responsible for invoking the network message processing at the time of its choosing and can interleave the progress of time on various hosts and network processing as it sees fit.

§Examples

Check the tests module for examples on how to use the simulation framework.

Structs§

  • Address
    An address is a combination of a hostname and an interface name.
  • Fleet
    A fleet is a collection of hosts in the simulation. It is responsible for running the simulation and processing network messages.
  • Host
    A host is a single Hydroflow process running in the simulation. It has a unique hostname and can communicate with other hosts over the virtual network. It has a collection of inboxes and outboxes.
  • HostBuilder
    A builder for constructing a host in the simulation.
  • Inbox
    An inbox is used by a host to receive messages for the process.
  • Outbox
    Processes can send messages to other processes by putting those messages in an outbox on their host.
  • ProcessBuilderContext
    Used in conjunction with the HostBuilder to construct a host in the simulation.

Traits§

  • MessageSender
    A message sender is used to send messages to an inbox on a host.

Type Aliases§

  • Hostname
    A hostname is a unique identifier for a host in the simulation. It is used to address messages to a specific host (and thus a specific Hydroflow process).
  • MessageWithAddress
    A message with an delivery address.