docs: update runbook with cargo run commands and matrix config

.cargo-husky/hooks/pre-push

@@ -1,8 +0,0 @@
-#!/bin/sh
-
-set -e
-
-echo "Running cargo nextest..."
-cargo nextest run --all-features
-
-echo "Pre-push checks passed!"

README.md

@@ -1,48 +1,109 @@
 # tls-pq-bench
 
-Reproducible benchmarking harness for comparing TLS 1.3 key exchange
+Reproducible benchmarking harness for comparing TLS 1.3 key exchange configurations.
-configurations:
 
-- Classical: X25519
+## Features
-- Hybrid PQ: X25519MLKEM768 (via `rustls` + `aws_lc_rs`)
 
-Primary metrics:
+- **Key Exchange Modes**
+  - Classical: `x25519`
+  - Hybrid PQ: `x25519mlkem768` (via `rustls` + `aws_lc_rs`)
 
-- Handshake latency
+- **Metrics**
-- TTLB (Time-to-Last-Byte)
+  - Handshake latency (nanoseconds)
+  - TTLB - Time-to-Last-Byte (nanoseconds)
 
-Secondary metrics:
+- **Benchmark Control**
+  - Warmup iterations (excluded from results)
+  - Configurable iterations
+  - Concurrency control (parallel connections)
+  - Configurable payload sizes
 
-- CPU cycles (`perf`)
+- **Reproducibility**
-- Memory behavior (optional: Valgrind/Massif)
+  - Structured logging (tracing)
-- Binary size (optional)
+  - Run ID for correlating logs
+  - Rust version, OS, arch recorded
+  - Command line arguments logged
+  - Negotiated cipher suite logged
 
-This repo is intended as the implementation for the empirical part of the
+- **Matrix Benchmarks**
-bachelor thesis (following the course thesis methodology).
+  - TOML configuration file support
+  - Run multiple benchmark configurations sequentially
+  - Each configuration: mode, payload, iters, warmup, concurrency
 
-## Non-goals
+## Quick Start
 
-- Not a general-purpose TLS load tester
+### Build
-- Not a cryptographic audit tool
-- Not a middlebox compatibility test suite (can be added later)
 
-## Quick start (local dev)
+```bash
+cargo build --release
+```
 
-1. Install Rust stable and Linux tooling:
+### Run Single Benchmark
-   - `perf`, `tcpdump` (optional), `jq`, `python3`
-2. Build:
-   - `cargo build --release`
 
-## Reproducibility notes
+Terminal 1 - Start server:
 
-All experiments should record:
+```bash
+./target/release/server --mode x25519 --listen 127.0.0.1:4433
+```
 
-- commit hash
+Terminal 2 - Run benchmark:
-- rustc version
+
-- CPU model and governor
+```bash
-- kernel version
+./target/release/runner --server 127.0.0.1:4433 --mode x25519 --iters 100 --warmup 10
-- rustls and aws-lc-rs versions
+```
-- exact CLI parameters and network profile
+
+### Run Matrix Benchmarks
+
+Create a config file (`matrix.toml`):
+
+```toml
+[[benchmarks]]
+server = "127.0.0.1:4433"
+mode = "x25519"
+payload = 1024
+iters = 100
+warmup = 10
+concurrency = 1
+
+[[benchmarks]]
+server = "127.0.0.1:4433"
+mode = "x25519mlkem768"
+payload = 1024
+iters = 100
+warmup = 10
+concurrency = 1
+```
+
+Run:
+
+```bash
+./target/release/runner --config matrix.toml
+```
+
+### Output
+
+Results are emitted as NDJSON to stdout or a file:
+
+```ndjson
+{"iteration":0,"mode":"x25519","payload_bytes":1024,"handshake_ns":500000,"ttlb_ns":650000}
+{"iteration":1,"mode":"x25519","payload_bytes":1024,"handshake_ns":490000,"ttlb_ns":620000}
+```
+
+### Logging
+
+Enable debug logs with `RUST_LOG`:
+
+```bash
+RUST_LOG=info ./target/release/runner --server 127.0.0.1:4433
+```
+
+Output includes:
+
+- Run ID for correlation
+- Rust version, OS, arch
+- Command used
+- Negotiated cipher suite
+- Benchmark configuration
 
 ## License
 

docs/TODO.md

@@ -24,13 +24,13 @@
 ## Milestone 3 -- KX selection (X25519 vs X25519MLKEM768) \[MUST\]
 
 - [x] rustls provider wiring (`aws_lc_rs` for PQ)
-- [ ] negotiated group logging (debug mode)
+- [X] negotiated group logging (debug mode)
 
 ## Milestone 4 -- Concurrency & runner [MUST]
 
 - [x] tokio-based runner
 - [X] concurrency control and warmup
-- [ ] matrix runner over (mode, payload, concurrency)
+- [X] matrix runner over (mode, payload, concurrency)
 
 ## Milestone 5 -- HTTP/1.1 mode (hyper) \[OPTIONAL\]
 

docs/runbook.md

@@ -20,13 +20,41 @@ Example:
 
 ```bash
 ./target/release/runner \
-  --server 1.2.3.4:4433 \
+    --server 1.2.3.4:4433 \
-  --mode x25519mlkem768 \
+    --mode x25519mlkem768 \
-  --payload-bytes 1024 \
+    --payload-bytes 1024 \
-  --concurrency 10 \
+    --concurrency 10 \
-  --iters 500 \
+    --iters 500 \
-  --warmup 50 \
+    --warmup 50 \
-  --out results.ndjson
+    --out results.ndjson
+```
+
+### Matrix Benchmarks
+
+Create a config file (`matrix.toml`):
+
+```toml
+[[benchmarks]]
+server = "1.2.3.4:4433"
+mode = "x25519"
+payload = 1024
+iters = 500
+warmup = 50
+concurrency = 1
+
+[[benchmarks]]
+server = "1.2.3.4:4433"
+mode = "x25519mlkem768"
+payload = 1024
+iters = 500
+warmup = 50
+concurrency = 1
+```
+
+Run matrix:
+
+```bash
+./target/release/runner --config matrix.toml
 ```
 
 ## 4) Collect perf stats (optional)
@@ -34,8 +62,7 @@ Example:
 Run on the client:
 
 ```bash
- perf stat -e cycles,instructions,cache-misses \
+perf stat -e cycles,instructions,cache-misses ./target/release/runner ...
-   ./target/release/runner ...
 ```
 
 ## 5) Summarize