feat: Add --fail-fast option to stop on first failure (pdsh -k compatible)

[inureyes]

Summary

• Add new --fail-fast / -k option for pdsh compatibility
• Stop execution immediately when any node fails (connection error or non-zero exit code)
• Cancel pending commands when failure is detected
• Report which node caused the failure with detailed error message

Changes

CLI (src/cli.rs)

• Added --fail-fast / -k flag with help text explaining pdsh compatibility
• Updated examples in help text to include fail-fast mode examples

Executor (src/executor/parallel.rs)

• Added fail_fast field to ParallelExecutor struct
• Added with_fail_fast() builder method
• Implemented execute_with_fail_fast() method using:
  • tokio::sync::watch channel for cancellation signaling
  • tokio::select! to race between semaphore acquisition and cancellation
  • Early return for cancelled tasks with appropriate error message
  • Detection and reporting of the first failure that triggered fail-fast

Integration (src/commands/exec.rs, src/app/dispatcher.rs)

• Pass fail_fast parameter through the execution pipeline

Tests (tests/fail_fast_test.rs)

• Added 10 unit tests covering:
  • CLI flag parsing (-k and --fail-fast)
  • Builder API for ParallelExecutor
  • Result classification (success, failure, error)
  • Flag combinations with other options
  • Parallelism settings compatibility

Documentation (README.md)

• Added fail-fast to features list
• Added usage examples for fail-fast mode

Test plan

• Run cargo test fail_fast - All 10 tests pass
• Run cargo clippy -- -D warnings - No warnings
• Run cargo fmt - Code is properly formatted
• Verify -k flag does not conflict with existing options
• Verify help text shows fail-fast examples

Related issues

• Closes feat: Add --fail-fast option to stop on first failure (pdsh -k compatibility) #94
• Part of feat: Add pdsh compatibility mode for drop-in replacement #91 (pdsh compatibility mode)

[inureyes]

Security & Performance Review

Analysis Summary

• Scope: changed-files
• Languages: Rust
• Total issues: 2
• Critical: 0 | High: 0 | Medium: 1 | Low: 1

Prioritized Fix Roadmap

MEDIUM

• UTF-8 String Slicing Panic (src/executor/parallel.rs:350-351): The code uses byte indexing (&first_line[..47]) to truncate error messages. If an error message contains multi-byte UTF-8 characters (e.g., Chinese, Japanese, emoji) and byte 47 lands in the middle of a character, this will cause a panic at runtime. This can crash the application when handling error messages from internationalized systems.

LOW

• Code duplication in error message truncation: The same truncation pattern appears in the normal execution path. While not a bug, this could be refactored for consistency.

Progress Log

• Currently: Fixing UTF-8 string slicing issue

Technical Details

Issue: UTF-8 String Boundary Violation

Current code:

let short_error = if first_line.len() > 50 {
    format!("{}...", &first_line[..47])
} else {
    first_line.to_string()
};

Problem: first_line.len() returns byte count, not character count. Slicing at byte index 47 can split a multi-byte UTF-8 character.

Proof of panic:

let s = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\u{4e2d}\u{6587}"; // 45 ASCII + Chinese
s[..47] // PANICS: byte 47 is inside '中' (bytes 45..48)

Fix approach: Use floor_char_boundary() (Rust 1.80+) or manually find safe boundary.

---

Reviewer: AI Code Reviewer

[inureyes]

Review Complete

Progress Log

• UTF-8 String Slicing Panic - Fixed in commit bbfa50e8
  • Changed &first_line[..47] to &first_line[..first_line.floor_char_boundary(47)]
  • Ensures safe string truncation for all Unicode content
• Code duplication - LOW priority, not addressed (suggestion only)

Verification

• cargo clippy -- -D warnings - Passes
• cargo test --test fail_fast_test - All 10 tests pass

Summary

The PR implements a solid --fail-fast / -k option for pdsh compatibility. The implementation correctly uses:

• tokio::sync::watch channel for cancellation signaling
• tokio::select! with biased selection for proper cancellation handling
• futures::future::select_all for efficient task completion monitoring

One bug was found and fixed: potential panic on non-ASCII error messages when truncating for display.

Overall Assessment: The implementation is well-designed and follows async Rust best practices. Ready for merge after the UTF-8 fix.