Benchmarking setup

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["proxy", "broker", "shared", "tests", "beam-lib"]
+members = ["proxy", "broker", "shared", "tests", "beam-lib", "benchmark"]
 resolver = "2"
 package.version = "0.11.0"
 

README.md

@@ -607,7 +607,10 @@ Confirm that your setup works by running `./dev/test noci`, which runs the tests
 
 To work with the environment, you may run `./dev/beamdev defaults` to see some helpful values, including the dev default URLs and a working authentication header.
 
-To run the dev setup with additional cargo flags like feature flags or the release flag you may run `dev/beamdev start <cargo flags>`, i.e. `dev/beamdev start --features sockets`.
+By default, `beamdev` builds and runs debug binaries. Cargo build flags can be
+passed after the command; use `dev/beamdev start --release` for optimized
+binaries or, for example, `dev/beamdev start --features sockets` to enable a
+feature.
 
 ## Production Environment & Certificate Infrastructure
 

benchmark/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "beam-benchmark"
+version = { workspace = true }
+edition = "2021"
+publish = false
+license = "Apache-2.0"
+
+[dependencies]
+anyhow = "1"
+beam-lib = { workspace = true, features = ["http-util"] }
+clap = { workspace = true }
+futures = { workspace = true }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["macros", "rt-multi-thread", "time"] }
+

benchmark/README.md

@@ -0,0 +1,31 @@
+# Beam benchmark
+
+`beam-benchmark` measures complete Beam task round trips. The same process acts as
+the sending app on proxy 1 and the receiving app on proxy 2:
+
+```text
+app1 -> proxy1 -> broker -> proxy2 -> app2
+app1 <- proxy1 <- broker <- proxy2 <- result
+```
+
+Start the development stack in one terminal:
+
+```sh
+./dev/beamdev start
+```
+
+Then run the benchmark in another terminal:
+
+```sh
+cargo run --release -p beam-benchmark -- --requests 1000 --concurrency 20
+```
+
+The defaults match `beamdev`: `localhost:8081`, `localhost:8082`,
+`app1.proxy1.broker`, `app2.proxy2.broker`, and API key `App1Secret`. Run with
+`--help` to override any of these, change payload size, or disable warm-up.
+
+Each measured cycle posts one task, retrieves it as the receiving app, submits a
+successful result, and retrieves that result as the sending app. The final report
+contains end-to-end throughput and latency percentiles as well as timings for the
+individual stages.
+