commonware_flood/
lib.rs

1//! Spam peers deployed to AWS EC2 with random messages.
2//!
3//! # Setup
4//!
5//! _To run this example, you must first install [Rust](https://www.rust-lang.org/tools/install) and [Docker](https://www.docker.com/get-started/)._
6//!
7//! ## Install `commonware-deployer`
8//!
9//! ```bash
10//! cargo install commonware-deployer
11//! ```
12//!
13//! ## Create Deployer Artifacts
14//!
15//! ```bash
16//! cargo run --bin setup -- --peers 3 --bootstrappers 1 --regions us-west-2,us-east-1,eu-west-1 --instance-type c7g.xlarge --storage-size 10 --storage-class gp3 --worker-threads 4 --message-size 1024 --message-backlog 16384 --mailbox-size 16384 --dashboard dashboard.json --output assets
17//! ```
18//!
19//! _We use 3 peers (instead of the 2 required to test connection performance) to demonstrate that peer discovery works._
20//!
21//! ## Build Flood Binary
22//!
23//! ### Build Cross-Platform Compiler
24//!
25//! ```bash
26//! docker build -t flood-builder .
27//! ```
28//!
29//! ### Compile Binary for ARM64
30//!
31//! ```bash
32//! docker run -it -v ${PWD}/../..:/monorepo flood-builder
33//! ```
34//!
35//! _Emitted binary `flood` is placed in `assets`._
36//!
37//! ## Deploy Flood Binary
38//!
39//! ```bash
40//! cd assets
41//! deployer ec2 create --config config.yaml
42//! ```
43//!
44//! # Monitor Performance on Grafana
45//!
46//! Visit `http://<monitoring-ip>:3000/d/flood`
47//!
48//! _This dashboard is only accessible from the IP used to deploy the infrastructure._
49//!
50//! ## (Optional) Update Flood Binary
51//!
52//! ## Re-Compile Binary for ARM64
53//!
54//! ```bash
55//! docker run -it -v ${PWD}/../..:/monorepo flood-builder
56//! ```
57//!
58//! ## Restart Flood Binary on EC2 Instances
59//!
60//! ```bash
61//! deployer ec2 update --config config.yaml
62//! ```
63//!
64//! # Destroy Infrastructure
65//!
66//! ```bash
67//! deployer ec2 destroy --config config.yaml
68//! ```
69//!
70//! # Debugging
71//!
72//! ## Missing AWS Credentials
73//!
74//! If `commonware-deployer` can't detect your AWS credentials, you'll see a "Request has expired." error:
75//!
76//! ```txt
77//! 2025-03-05T01:36:47.550105Z  INFO deployer::ec2::create: created EC2 client region="eu-west-1"
78//! 2025-03-05T01:36:48.268330Z ERROR deployer: failed to create EC2 deployment error=AwsEc2(Unhandled(Unhandled { source: ErrorMetadata { code: Some("RequestExpired"), message: Some("Request has expired."), extras: Some({"aws_request_id": "006f6b92-4965-470d-8eac-7c9644744bdf"}) }, meta: ErrorMetadata { code: Some("RequestExpired"), message: Some("Request has expired."), extras: Some({"aws_request_id": "006f6b92-4965-470d-8eac-7c9644744bdf"}) } }))
79//! ```
80//!
81//! ## EC2 Throttling
82//!
83//! EC2 instances may throttle network traffic if a workload exceeds the allocation for a particular instance type. To check
84//! if an instance is throttled, SSH into the instance and run:
85//!
86//! ```bash
87//! ethtool -S ens5 | grep "allowance"
88//! ```
89//!
90//! If throttled, you'll see a non-zero value for some "allowance" item:
91//!
92//! ```txt
93//! bw_in_allowance_exceeded: 0
94//! bw_out_allowance_exceeded: 14368
95//! pps_allowance_exceeded: 0
96//! conntrack_allowance_exceeded: 0
97//! linklocal_allowance_exceeded: 0
98//! ```
99
100#![doc(
101    html_logo_url = "https://commonware.xyz/imgs/rustdoc_logo.svg",
102    html_favicon_url = "https://commonware.xyz/favicon.ico"
103)]
104
105use serde::{Deserialize, Serialize};
106
107/// Configuration for flood.
108#[derive(Deserialize, Serialize)]
109pub struct Config {
110    pub private_key: String,
111    pub port: u16,
112    pub allowed_peers: Vec<String>,
113    pub bootstrappers: Vec<String>,
114    pub worker_threads: usize,
115    pub message_size: u32,
116    pub message_backlog: usize,
117    pub mailbox_size: usize,
118    pub instrument: bool,
119}
commonware_flood/lib.rs

commonware_flood/
lib.rs
