Module hydroflow::util::simulation

source ·
Expand description

§Hydroflow Deterministic Simulation Testing Framework

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

It can be used to test complex interactions between multiple Hydroflow transducers in a deterministic manner by running them in a single-threaded environment. The framework also provides a “virtual network” implementation that allows production transducers 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 transducers (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 transducer wishes to send a message to another transducer, 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 transducer 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 transducer. 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 transducer 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 transducer.
  • Outbox
    Transducers can send messages to other transducers by putting those messages in an outbox on their host.
  • TransducerBuilderContext
    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 transducer).
  • MessageWithAddress
    A message with an delivery address.