Skip to content

feat: Add --connect-timeout option for connection timeout (pdsh -t compatibility) #96

Closed

Description

@inureyes

Summary

Add a new --connect-timeout option to bssh that sets the SSH connection timeout separately from the command execution timeout. This is a prerequisite for pdsh compatibility mode.

Parent Issue

Part of #91 (pdsh compatibility mode) - Phase 1: New Options for Feature Parity

Background

pdsh distinguishes between two types of timeouts:

  • -t seconds: Connection timeout (how long to wait for SSH connection, default 10s)
  • -u seconds: Command timeout (how long to allow command to run)

Currently bssh has --timeout which controls command execution timeout, but lacks a separate connection timeout option. This distinction is important for:

  • Slow networks where connection takes longer
  • Fast operations where command should timeout quickly but connection can take time
  • Fine-grained control over failure modes

Current Behavior

// In src/ssh/client.rs
const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(30);

The connection timeout is currently hardcoded at 30 seconds.

Proposed Implementation

CLI Interface

# Default: 30s connection timeout
bssh -H "node1,node2" "uptime"

# Custom connection timeout
bssh -H "node1,node2" --connect-timeout 10 "uptime"

# Combined with command timeout
bssh -H "node1,node2" --connect-timeout 5 --timeout 60 "long-command"

Option Definition

#[arg(
    long = "connect-timeout",
    default_value = "30",
    value_name = "SECONDS",
    help = "SSH connection timeout in seconds [default: 30]"
)]
pub connect_timeout: u64,

Implementation Tasks

  • Add --connect-timeout option to Cli struct in src/cli.rs
  • Pass connection timeout to SSH client configuration
  • Modify src/ssh/client.rs to accept configurable timeout
  • Update executor to use CLI-provided timeout
  • Add unit tests for timeout behavior
  • Update help text and examples

Acceptance Criteria

  • --connect-timeout N sets SSH connection timeout to N seconds
  • Default remains 30 seconds for backward compatibility
  • Connection timeout is independent of --timeout (command timeout)
  • Timeout of 0 should be disallowed or mean "no timeout" (needs decision)
  • Clear error message when connection times out
  • Works correctly with parallel connections

Technical Considerations

  • Currently tokio::time::timeout wraps the connect call
  • May need to propagate timeout value through connection chain
  • Consider if this should also apply to authentication timeout

Notes

  • Using --connect-timeout (long form only) to avoid conflict with -t (which is --tty in bssh)
  • In pdsh compatibility mode, -t will map to --connect-timeout

Related

Activity

  1. inureyes commented on Dec 16, 2025

    @inureyes
    MemberAuthor

    Implementation Complete

    The --connect-timeout option has been fully implemented with all code review issues fixed.

    Changes Made

    Commit 4c6ffe0: feat: Add --connect-timeout option for SSH connection timeout

    • Added --connect-timeout CLI option with default value of 30 seconds
    • Integrated with executor and SSH client layers
    • Works with exec and ping commands

    Commit e068545: fix: Propagate connect_timeout through all SSH connection paths

    • Fixed jump host connections to use user-specified timeout
    • Propagated timeout to all file transfer operations (upload/download)
    • Added validation to reject value of 0 (minimum is 1 second)
    • Updated help text

    Usage

    # Default 30 second connection timeout
    bssh -H "node1,node2" "uptime"
    
    # Custom connection timeout
    bssh --connect-timeout 10 -H "node1,node2" "uptime"
    
    # Combined with command timeout
    bssh --connect-timeout 5 --timeout 60 -H "node1,node2" "long-command"

    Acceptance Criteria Met

    • --connect-timeout N sets SSH connection timeout to N seconds
    • Default remains 30 seconds for backward compatibility
    • Connection timeout is independent of --timeout (command timeout)
    • Timeout of 0 is disallowed (minimum value validation)
    • Clear error message when connection times out
    • Works correctly with parallel connections
    • Works with jump host connections
    • Works with file transfer operations
  2. self-assigned this
    on Dec 16, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions