rustress 0.1.1

High-performance load testing engine with an interactive terminal dashboard. Open-loop (RPS) and closed-loop (virtual users) load models with live p50/p90/p95/p99 latency telemetry.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
use std::time::Instant;

use reqwest::Response;
use std::process::Stdio;

use tokio::io::AsyncReadExt;
use tokio::process::Command;

use crate::core::config::Config;
use crate::core::constants::MAX_CAPTURED_BODY_BYTES;
use crate::core::result::ExperimentResult;
use crate::runner::request::PreparedRequest;
use crate::runner::stats::RunStats;
use crate::templates::{TemplateContext, TemplateEngine};

/// Appended to a captured body that was cut short at the capture cap, so a
/// truncated diagnostic is never mistaken for a complete one.
///
/// Public so a report consumer — or a test — can detect truncation from the
/// constant rather than by matching a string literal that will drift.
pub const TRUNCATION_MARKER: &str = "\n...[truncated]";

/// Outcome of a single HTTP exchange, with body capture already bounded.
struct HttpOutcome {
    status: u16,
    bytes: u64,
    captured_body: Option<String>,
    error: Option<String>,
}

/// Execute a single HTTP request and fold the outcome into `stats`.
pub async fn execute_http(
    client: &reqwest::Client,
    prepared: &PreparedRequest,
    engine: &TemplateEngine,
    ctx: &TemplateContext,
    scheduled: Instant,
    stats: &RunStats,
) {
    let actual_start = Instant::now();
    let queue_wait = actual_start.saturating_duration_since(scheduled);

    let request = match prepared.build(client, engine, ctx) {
        Ok(request) => request,
        Err(message) => {
            stats.record(failed_outcome(
                actual_start,
                scheduled,
                ctx,
                0,
                message,
                None,
            ));
            return;
        }
    };

    let outcome = match request.send().await {
        Ok(response) => read_response(response).await,
        Err(e) => HttpOutcome {
            status: 0,
            bytes: 0,
            captured_body: None,
            error: Some(clean_error_msg(&e.to_string())),
        },
    };

    // A 2xx status alone is not a success. If the body stream failed, the
    // response was unusable, and counting it as a success lets a run report
    // 100% success against a target returning nothing but broken payloads
    // while `error_counts` disagrees with the headline number.
    let success = outcome.error.is_none() && (200..300).contains(&outcome.status);
    stats.record(ExperimentResult {
        timestamp: chrono::Utc::now(),
        latency: Instant::now().saturating_duration_since(scheduled),
        service_time: Instant::now().saturating_duration_since(actual_start),
        queue_wait,
        status: outcome.status,
        success,
        bytes: outcome.bytes as i64,
        user_id: ctx.user_id.clone(),
        query: prepared.label.clone(),
        error: outcome.error,
        response_body: outcome.captured_body,
    });
}

/// Drain a response body to EOF, counting bytes and capturing a bounded prefix.
///
/// The body is never fully materialised: bytes are counted as they stream past
/// so the throughput metric stays correct for chunked responses, which report
/// no `content-length`, and only the first [`MAX_CAPTURED_BODY_BYTES`] are
/// retained because a load generator cannot trust the size of a body from a
/// target it does not control.
///
/// Draining to EOF is deliberate. Abandoning the body early would forfeit
/// connection reuse, so a target serving large bodies would pay a fresh
/// TCP+TLS handshake on every request — and that handshake would land inside
/// the measured service time, corrupting the result.
async fn read_response(mut response: Response) -> HttpOutcome {
    let status = response.status().as_u16();
    let mut bytes = 0u64;
    let mut captured: Vec<u8> = Vec::new();
    let mut truncated = false;
    let mut stream_error = None;

    loop {
        match response.chunk().await {
            Ok(Some(chunk)) => {
                bytes += chunk.len() as u64;
                if captured.len() < MAX_CAPTURED_BODY_BYTES {
                    let room = MAX_CAPTURED_BODY_BYTES - captured.len();
                    let take = room.min(chunk.len());
                    captured.extend_from_slice(&chunk[..take]);
                    if take < chunk.len() {
                        truncated = true;
                    }
                } else {
                    truncated = true;
                }
            }
            Ok(None) => break,
            Err(e) => {
                stream_error = Some(clean_error_msg(&e.to_string()));
                break;
            }
        }
    }

    let captured_body = if status >= 400 && !captured.is_empty() {
        let mut text = String::from_utf8_lossy(&captured).into_owned();
        if truncated {
            text.push_str(TRUNCATION_MARKER);
        }
        Some(text)
    } else {
        None
    };

    HttpOutcome {
        status,
        bytes,
        captured_body,
        error: stream_error,
    }
}

/// Execute a single shell command via `sh -c` and fold the outcome into `stats`.
pub async fn execute_script(
    cfg: &Config,
    engine: &TemplateEngine,
    ctx: &TemplateContext,
    scheduled: Instant,
    stats: &RunStats,
) {
    let actual_start = Instant::now();
    let queue_wait = actual_start.saturating_duration_since(scheduled);

    let raw = cfg.command.as_deref().unwrap_or_default();
    let command = if raw.contains("{{") {
        engine
            .execute_str(raw, ctx)
            .unwrap_or_else(|_| raw.to_string())
    } else {
        raw.to_string()
    };

    let output = match run_script_capped(&command).await {
        Ok(output) => output,
        Err(e) => {
            stats.record(failed_outcome(
                actual_start,
                scheduled,
                ctx,
                0,
                e.to_string(),
                Some("shell".to_string()),
            ));
            return;
        }
    };

    let success = output.success;
    let status = if success {
        200
    } else {
        output.code.unwrap_or(500) as u16
    };
    let error = (!success).then(|| clean_error_msg(&output.stderr));
    let captured = (!success)
        .then(|| truncate_capture(&output.stderr))
        .filter(|s| !s.is_empty());

    stats.record(ExperimentResult {
        timestamp: chrono::Utc::now(),
        latency: Instant::now().saturating_duration_since(scheduled),
        service_time: Instant::now().saturating_duration_since(actual_start),
        queue_wait,
        status,
        success,
        bytes: output.stdout_bytes as i64,
        user_id: ctx.user_id.clone(),
        query: "script".to_string(),
        error,
        response_body: captured,
    });
}

/// Captured script result, with stdout counted but only stderr retained.
struct ScriptOutput {
    /// Total bytes the script wrote to stdout, counted as it streamed.
    stdout_bytes: u64,
    /// Exit status code, or 128 when the process was signalled.
    code: Option<i32>,
    /// Whether the process exited successfully.
    success: bool,
    /// Captured stderr, truncated to the capture cap.
    stderr: String,
}

/// Run `sh -c command`, counting stdout without retaining it.
///
/// `Command::output()` buffers *both* streams to EOF, so a script that prints
/// without bound exhausts host memory for as long as it runs. A target's
/// response body is attacker-controlled; a script's output is the same class of
/// input and gets the same treatment. stdout is drained and counted but
/// discarded -- only its length is a measurement, which is exactly the same
/// reasoning the HTTP path uses for a response body -- and stderr is retained
/// up to the capture cap so a failure still carries a diagnosable message.
async fn run_script_capped(command: &str) -> std::io::Result<ScriptOutput> {
    let mut child = Command::new("sh")
        .arg("-c")
        .arg(command)
        .stdin(Stdio::null())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()?;

    let mut stdout = child.stdout.take().expect("stdout was piped");
    let mut stderr = child.stderr.take().expect("stderr was piped");

    let stdout_task = tokio::spawn(async move {
        let mut buf = [0u8; 8 * 1024];
        let mut total = 0u64;
        loop {
            match stdout.read(&mut buf).await {
                Ok(0) => break,
                Ok(n) => total += n as u64,
                Err(_) => break,
            }
        }
        total
    });

    let mut retained: Vec<u8> = Vec::new();
    let mut stderr_buf = [0u8; 8 * 1024];
    loop {
        match stderr.read(&mut stderr_buf).await {
            Ok(0) => break,
            Ok(n) => {
                if retained.len() < MAX_CAPTURED_BODY_BYTES {
                    let room = MAX_CAPTURED_BODY_BYTES - retained.len();
                    let take = room.min(n);
                    retained.extend_from_slice(&stderr_buf[..take]);
                }
            }
            Err(_) => break,
        }
    }

    let stdout_bytes = stdout_task.await.unwrap_or(0);
    let status = child.wait().await?;

    let mut stderr = String::from_utf8_lossy(&retained).into_owned();
    if retained.len() == MAX_CAPTURED_BODY_BYTES {
        stderr.push_str(TRUNCATION_MARKER);
    }

    Ok(ScriptOutput {
        stdout_bytes,
        code: status.code(),
        success: status.success(),
        stderr,
    })
}

/// Build a failed result for a request that never reached the wire.
fn failed_outcome(
    actual_start: Instant,
    scheduled: Instant,
    ctx: &TemplateContext,
    status: u16,
    error: String,
    query: Option<String>,
) -> ExperimentResult {
    ExperimentResult {
        timestamp: chrono::Utc::now(),
        latency: Instant::now().saturating_duration_since(scheduled),
        service_time: Instant::now().saturating_duration_since(actual_start),
        queue_wait: actual_start.saturating_duration_since(scheduled),
        status,
        success: false,
        bytes: 0,
        user_id: ctx.user_id.clone(),
        query: query.unwrap_or_else(|| "custom".to_string()),
        error: Some(error),
        response_body: None,
    }
}

/// Truncate a diagnostic string to the capture cap.
fn truncate_capture(text: &str) -> String {
    text.chars().take(MAX_CAPTURED_BODY_BYTES).collect()
}

/// Strip redundant transport prefixes from a reqwest error message.
fn clean_error_msg(message: &str) -> String {
    let interesting =
        message.contains("dial") || message.contains("timeout") || message.contains("connect");
    if interesting {
        if let Some(idx) = message.rfind(": ") {
            return message[idx + 2..].to_string();
        }
    }
    message.to_string()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn clean_error_msg_strips_transport_prefix() {
        assert_eq!(
            clean_error_msg("error sending request for url (http://x/): connection refused"),
            "connection refused"
        );
    }

    #[test]
    fn clean_error_msg_preserves_uninteresting_message() {
        let msg = "builder error: invalid header";
        assert_eq!(clean_error_msg(msg), msg);
    }

    #[test]
    fn truncate_capture_bounds_length() {
        let huge = "a".repeat(MAX_CAPTURED_BODY_BYTES * 4);
        let capped = truncate_capture(&huge);
        assert_eq!(capped.chars().count(), MAX_CAPTURED_BODY_BYTES);
    }

    #[test]
    fn truncate_capture_passes_short_text_through() {
        assert_eq!(truncate_capture("boom"), "boom");
    }

    #[test]
    fn truncate_capture_respects_char_boundaries() {
        let multibyte = "é".repeat(MAX_CAPTURED_BODY_BYTES);
        let capped = truncate_capture(&multibyte);
        assert_eq!(capped.chars().count(), MAX_CAPTURED_BODY_BYTES);
    }

    #[test]
    fn truncate_capture_at_exactly_the_cap_is_unchanged() {
        let text = "a".repeat(MAX_CAPTURED_BODY_BYTES);
        assert_eq!(
            truncate_capture(&text),
            text,
            "a capture of exactly the cap is complete and must pass through byte \
             for byte, marker or not"
        );
    }

    #[test]
    fn truncate_capture_never_splits_a_multibyte_character() {
        let multibyte = "é".repeat(MAX_CAPTURED_BODY_BYTES + 8);
        let capped = truncate_capture(&multibyte);
        assert_eq!(capped.chars().count(), MAX_CAPTURED_BODY_BYTES);
        assert!(
            std::str::from_utf8(capped.as_bytes()).is_ok(),
            "a cut diagnostic must remain valid UTF-8; a split character is written \
             into a CSV and JSON report as a replacement glyph"
        );
    }

    #[test]
    fn a_truncated_capture_is_one_char_shorter_not_one_byte_shorter() {
        let text = "a".repeat(MAX_CAPTURED_BODY_BYTES + 1);
        let capped = truncate_capture(&text);
        assert_eq!(capped.chars().count(), MAX_CAPTURED_BODY_BYTES);
        assert_eq!(capped.len(), MAX_CAPTURED_BODY_BYTES);
    }

    /// A script's output is untrusted input, exactly like a response body.
    /// `Command::output()` buffered it to EOF, so a script that printed without
    /// bound exhausted host memory. Real `sh`, no mock.
    #[tokio::test]
    async fn a_runaway_script_cannot_grow_the_capture() {
        let out = run_script_capped("head -c 200000 /dev/zero | tr '\\0' 'E' 1>&2; exit 1")
            .await
            .expect("script runs");

        assert!(!out.success, "exit 1 must be reported as a failure");
        assert_eq!(
            out.stderr.len(),
            MAX_CAPTURED_BODY_BYTES + TRUNCATION_MARKER.len(),
            "stderr capture must be exactly the cap plus the truncation marker"
        );
        assert!(
            out.stderr.ends_with(TRUNCATION_MARKER),
            "a truncated capture must say so explicitly"
        );
    }

    /// stdout is counted but never retained, because only its length is a
    /// measurement. Retaining it is the bug this replaced.
    #[tokio::test]
    async fn stdout_is_counted_but_not_retained() {
        let out = run_script_capped("head -c 5000 /dev/zero | tr '\\0' 'o'")
            .await
            .expect("script runs");

        assert!(out.success, "exit 0 must be reported as a success");
        assert_eq!(
            out.stdout_bytes, 5_000,
            "stdout bytes must be counted exactly"
        );
        assert!(
            out.stderr.is_empty(),
            "stderr must be empty for a clean script, got {} bytes",
            out.stderr.len()
        );
    }
}