Module: Capistrano::Configuration::Connections

Included in:
Capistrano::Configuration
Defined in:
lib/capistrano/configuration/connections.rb

Defined Under Namespace

Classes: DefaultConnectionFactory

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#sessions ⇒ Object (readonly)

A hash of the SSH sessions that are currently open and available. Because sessions are constructed lazily, this will only contain connections to those servers that have been the targets of one or more executed tasks.



28
29
30
 
# File 'lib/capistrano/configuration/connections.rb', line 28

def sessions
  @sessions
end

Class Method Details

.included(base) ⇒ Object

:nodoc:



7
8
9
10
 
# File 'lib/capistrano/configuration/connections.rb', line 7

def self.included(base) #:nodoc:
  base.send :alias_method, :initialize_without_connections, :initialize
  base.send :alias_method, :initialize, :initialize_with_connections
end

Instance Method Details

#connect!(options = {}) ⇒ Object

Used to force connections to be made to the current task’s servers. Connections are normally made lazily in Capistrano–you can use this to force them open before performing some operation that might be time-sensitive.



51
52
53
 
# File 'lib/capistrano/configuration/connections.rb', line 51

def connect!(options={})
  execute_on_servers(options) { }
end

#connection_factory ⇒ Object

Returns the object responsible for establishing new SSH connections. The factory will respond to #connect_to, which can be used to establish connections to servers defined via ServerDefinition objects.



58
59
60
61
62
63
64
65
66
67
 
# File 'lib/capistrano/configuration/connections.rb', line 58

def connection_factory
  @connection_factory ||= begin
    if exists?(:gateway)
      logger.debug "establishing connection to gateway `#{fetch(:gateway)}'"
      Gateway.new(ServerDefinition.new(fetch(:gateway)), self)
    else
      DefaultConnectionFactory.new(self)
    end
  end
end

#establish_connections_to(servers) ⇒ Object

Ensures that there are active sessions for each server in the list.



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
 
# File 'lib/capistrano/configuration/connections.rb', line 70

def establish_connections_to(servers)
  failed_servers = []

  # This attemps to work around the problem where SFTP uploads hang
  # for some people. A bit of investigating seemed to reveal that the
  # hang only occurred when the SSH connections were established async,
  # so this setting allows people to at least work around the problem.
  if fetch(:synchronous_connect, false)
    logger.trace "synchronous_connect: true"
    Array(servers).each { |server| safely_establish_connection_to(server, failed_servers) }
  else
    # force the connection factory to be instantiated synchronously,
    # otherwise we wind up with multiple gateway instances, because
    # each connection is done in parallel.
    connection_factory

    threads = Array(servers).map { |server| establish_connection_to(server, failed_servers) }
    threads.each { |t| t.join }
  end

  if failed_servers.any?
    errors = failed_servers.map { |h| "#{h[:server]} (#{h[:error].class}: #{h[:error].message})" }
    error = ConnectionError.new("connection failed for: #{errors.join(', ')}")
    error.hosts = failed_servers.map { |h| h[:server] }
    raise error
  end
end

#execute_on_servers(options = {}) ⇒ Object

Determines the set of servers within the current task’s scope and establishes connections to them, and then yields that list of servers.

Raises:

  • (ArgumentError) 


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
 
# File 'lib/capistrano/configuration/connections.rb', line 101

def execute_on_servers(options={})
  raise ArgumentError, "expected a block" unless block_given?

  if task = current_task
    servers = find_servers_for_task(task, options)

    if servers.empty?
      raise Capistrano::NoMatchingServersError, "`#{task.fully_qualified_name}' is only run for servers matching #{task.options.inspect}, but no servers matched"
    end

    if task.continue_on_error?
      servers.delete_if { |s| has_failed?(s) }
      return if servers.empty?
    end
  else
    servers = find_servers(options)
    raise Capistrano::NoMatchingServersError, "no servers found to match #{options.inspect}" if servers.empty?
  end

  servers = [servers.first] if options[:once]
  logger.trace "servers: #{servers.map { |s| s.host }.inspect}"

  # establish connections to those servers, as necessary
  begin
    establish_connections_to(servers)
  rescue ConnectionError => error
    raise error unless task && task.continue_on_error?
    error.hosts.each do |h|
      servers.delete(h)
      failed!(h)
    end
  end

  begin
    yield servers
  rescue RemoteError => error
    raise error unless task && task.continue_on_error?
    error.hosts.each { |h| failed!(h) }
  end
end

#failed!(server) ⇒ Object

Indicate that the given server could not be connected to.



37
38
39
 
# File 'lib/capistrano/configuration/connections.rb', line 37

def failed!(server)
  @failed_sessions << server
end

#has_failed?(server) ⇒ Boolean

Query whether previous connection attempts to the given server have failed.



43
44
45
 
# File 'lib/capistrano/configuration/connections.rb', line 43

def has_failed?(server)
  @failed_sessions.include?(server)
end

#initialize_with_connections(*args) ⇒ Object

:nodoc:



30
31
32
33
34
 
# File 'lib/capistrano/configuration/connections.rb', line 30

def initialize_with_connections(*args) #:nodoc:
  initialize_without_connections(*args)
  @sessions = {}
  @failed_sessions = []
end