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.
# File lib/capistrano/configuration/connections.rb, line 100 100: def connect!(options={}) 101: execute_on_servers(options) { } 102: end
Returns the object responsible for establishing new SSH connections. The factory will respond to #, which can be used to establish connections to servers defined via ServerDefinition objects.
# File lib/capistrano/configuration/connections.rb, line 107 107: def connection_factory 108: @connection_factory ||= begin 109: if exists?(:gateway) 110: logger.debug "establishing connection to gateway `#{fetch(:gateway).inspect}'" 111: GatewayConnectionFactory.new(fetch(:gateway), self) 112: else 113: DefaultConnectionFactory.new(self) 114: end 115: end 116: end
Ensures that there are active sessions for each server in the list.
# File lib/capistrano/configuration/connections.rb, line 119 119: def establish_connections_to(servers) 120: failed_servers = [] 121: 122: # force the connection factory to be instantiated synchronously, 123: # otherwise we wind up with multiple gateway instances, because 124: # each connection is done in parallel. 125: connection_factory 126: 127: threads = Array(servers).map { |server| establish_connection_to(server, failed_servers) } 128: threads.each { |t| t.join } 129: 130: if failed_servers.any? 131: errors = failed_servers.map { |h| "#{h[:server]} (#{h[:error].class}: #{h[:error].message})" } 132: error = ConnectionError.new("connection failed for: #{errors.join(', ')}") 133: error.hosts = failed_servers.map { |h| h[:server] } 134: raise error 135: end 136: end
Determines the set of servers within the current task’s scope and establishes connections to them, and then yields that list of servers.
# File lib/capistrano/configuration/connections.rb, line 152 152: def execute_on_servers(options={}) 153: raise ArgumentError, "expected a block" unless block_given? 154: 155: if task = current_task 156: servers = find_servers_for_task(task, options) 157: 158: if servers.empty? 159: if ENV['HOSTFILTER'] || task.options.merge(options)[:on_no_matching_servers] == :continue 160: logger.info "skipping `#{task.fully_qualified_name}' because no servers matched" 161: return 162: else 163: raise Capistrano::NoMatchingServersError, "`#{task.fully_qualified_name}' is only run for servers matching #{task.options.inspect}, but no servers matched" 164: end 165: end 166: 167: if task.continue_on_error? 168: servers.delete_if { |s| has_failed?(s) } 169: return if servers.empty? 170: end 171: else 172: servers = find_servers(options) 173: if servers.empty? 174: raise Capistrano::NoMatchingServersError, "no servers found to match #{options.inspect}" if options[:on_no_matching_servers] != :continue 175: return 176: end 177: end 178: 179: servers = [servers.first] if options[:once] 180: logger.trace "servers: #{servers.map { |s| s.host }.inspect}" 181: 182: max_hosts = (options[:max_hosts] || (task && task.max_hosts) || servers.size).to_i 183: is_subset = max_hosts < servers.size 184: 185: # establish connections to those servers in groups of max_hosts, as necessary 186: servers.each_slice(max_hosts) do |servers_slice| 187: begin 188: establish_connections_to(servers_slice) 189: rescue ConnectionError => error 190: raise error unless task && task.continue_on_error? 191: error.hosts.each do |h| 192: servers_slice.delete(h) 193: failed!(h) 194: end 195: end 196: 197: begin 198: yield servers_slice 199: rescue RemoteError => error 200: raise error unless task && task.continue_on_error? 201: error.hosts.each { |h| failed!(h) } 202: end 203: 204: # if dealing with a subset (e.g., :max_hosts is less than the 205: # number of servers available) teardown the subset of connections 206: # that were just made, so that we can make room for the next subset. 207: teardown_connections_to(servers_slice) if is_subset 208: end 209: end
Indicate that the given server could not be connected to.
# File lib/capistrano/configuration/connections.rb, line 86 86: def failed!(server) 87: Thread.current[:failed_sessions] << server 88: end
Query whether previous connection attempts to the given server have failed.
# File lib/capistrano/configuration/connections.rb, line 92 92: def has_failed?(server) 93: Thread.current[:failed_sessions].include?(server) 94: end
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. Stored on a per-thread basis to improve thread-safety.
# File lib/capistrano/configuration/connections.rb, line 75 75: def sessions 76: Thread.current[:sessions] ||= {} 77: end
Destroys sessions for each server in the list.
# File lib/capistrano/configuration/connections.rb, line 139 139: def teardown_connections_to(servers) 140: servers.each do |server| 141: begin 142: sessions.delete(server).close 143: rescue IOError 144: # the TCP connection is already dead 145: end 146: end 147: end
We establish the connection by creating a thread in a new method—this prevents problems with the thread’s scope seeing the wrong ‘server’ variable if the thread just happens to take too long to start up.
# File lib/capistrano/configuration/connections.rb, line 216 216: def establish_connection_to(server, failures=nil) 217: current_thread = Thread.current 218: Thread.new { safely_establish_connection_to(server, current_thread, failures) } 219: end
# File lib/capistrano/configuration/connections.rb, line 221 221: def safely_establish_connection_to(server, thread, failures=nil) 222: thread[:sessions] ||= {} 223: thread[:sessions][server] ||= connection_factory.connect_to(server) 224: rescue Exception => err 225: raise unless failures 226: failures << { :server => server, :error => err } 227: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.