Module Capistrano::Configuration::Connections
In: lib/capistrano/configuration/connections.rb
lib/capistrano/configuration/connections.rb

Methods

Public Instance methods

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.

[Source]

    # File lib/capistrano/configuration/connections.rb, line 80
80:       def connect!(options={})
81:         execute_on_servers(options) { }
82:       end

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.

[Source]

    # File lib/capistrano/configuration/connections.rb, line 80
80:       def connect!(options={})
81:         execute_on_servers(options) { }
82:       end

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.

[Source]

    # File lib/capistrano/configuration/connections.rb, line 87
87:       def connection_factory
88:         @connection_factory ||= begin
89:           if exists?(:gateway)
90:             logger.debug "establishing connection to gateway `#{fetch(:gateway)}'"
91:             GatewayConnectionFactory.new(fetch(:gateway), self)
92:           else
93:             DefaultConnectionFactory.new(self)
94:           end
95:         end
96:       end

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.

[Source]

    # File lib/capistrano/configuration/connections.rb, line 87
87:       def connection_factory
88:         @connection_factory ||= begin
89:           if exists?(:gateway)
90:             logger.debug "establishing connection to gateway `#{fetch(:gateway)}'"
91:             GatewayConnectionFactory.new(fetch(:gateway), self)
92:           else
93:             DefaultConnectionFactory.new(self)
94:           end
95:         end
96:       end

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

[Source]

     # File lib/capistrano/configuration/connections.rb, line 99
 99:       def establish_connections_to(servers)
100:         failed_servers = []
101: 
102:         # force the connection factory to be instantiated synchronously,
103:         # otherwise we wind up with multiple gateway instances, because
104:         # each connection is done in parallel.
105:         connection_factory
106: 
107:         threads = Array(servers).map { |server| establish_connection_to(server, failed_servers) }
108:         threads.each { |t| t.join }
109: 
110:         if failed_servers.any?
111:           errors = failed_servers.map { |h| "#{h[:server]} (#{h[:error].class}: #{h[:error].message})" }
112:           error = ConnectionError.new("connection failed for: #{errors.join(', ')}")
113:           error.hosts = failed_servers.map { |h| h[:server] }
114:           raise error
115:         end
116:       end

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

[Source]

     # File lib/capistrano/configuration/connections.rb, line 99
 99:       def establish_connections_to(servers)
100:         failed_servers = []
101: 
102:         # force the connection factory to be instantiated synchronously,
103:         # otherwise we wind up with multiple gateway instances, because
104:         # each connection is done in parallel.
105:         connection_factory
106: 
107:         threads = Array(servers).map { |server| establish_connection_to(server, failed_servers) }
108:         threads.each { |t| t.join }
109: 
110:         if failed_servers.any?
111:           errors = failed_servers.map { |h| "#{h[:server]} (#{h[:error].class}: #{h[:error].message})" }
112:           error = ConnectionError.new("connection failed for: #{errors.join(', ')}")
113:           error.hosts = failed_servers.map { |h| h[:server] }
114:           raise error
115:         end
116:       end

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

[Source]

     # File lib/capistrano/configuration/connections.rb, line 129
129:       def execute_on_servers(options={})
130:         raise ArgumentError, "expected a block" unless block_given?
131: 
132:         if task = current_task
133:           servers = find_servers_for_task(task, options)
134: 
135:           if servers.empty?
136:             if ENV['HOSTFILTER']
137:               logger.info "skipping `#{task.fully_qualified_name}' because no servers matched"
138:               return
139:             else
140:               raise Capistrano::NoMatchingServersError, "`#{task.fully_qualified_name}' is only run for servers matching #{task.options.inspect}, but no servers matched"
141:             end
142:           end
143: 
144:           if task.continue_on_error?
145:             servers.delete_if { |s| has_failed?(s) }
146:             return if servers.empty?
147:           end
148:         else
149:           servers = find_servers(options)
150:           raise Capistrano::NoMatchingServersError, "no servers found to match #{options.inspect}" if servers.empty?
151:         end
152: 
153:         servers = [servers.first] if options[:once]
154:         logger.trace "servers: #{servers.map { |s| s.host }.inspect}"
155: 
156:         max_hosts = (options[:max_hosts] || (task && task.max_hosts) || servers.size).to_i
157:         is_subset = max_hosts < servers.size
158: 
159:         # establish connections to those servers in groups of max_hosts, as necessary
160:         servers.each_slice(max_hosts) do |servers_slice|
161:           begin
162:             establish_connections_to(servers_slice)
163:           rescue ConnectionError => error
164:             raise error unless task && task.continue_on_error?
165:             error.hosts.each do |h|
166:               servers_slice.delete(h)
167:               failed!(h)
168:             end
169:           end
170: 
171:           begin
172:             yield servers_slice
173:           rescue RemoteError => error
174:             raise error unless task && task.continue_on_error?
175:             error.hosts.each { |h| failed!(h) }
176:           end
177: 
178:           # if dealing with a subset (e.g., :max_hosts is less than the
179:           # number of servers available) teardown the subset of connections
180:           # that were just made, so that we can make room for the next subset.
181:           teardown_connections_to(servers_slice) if is_subset
182:         end
183:       end

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

[Source]

     # File lib/capistrano/configuration/connections.rb, line 129
129:       def execute_on_servers(options={})
130:         raise ArgumentError, "expected a block" unless block_given?
131: 
132:         if task = current_task
133:           servers = find_servers_for_task(task, options)
134: 
135:           if servers.empty?
136:             if ENV['HOSTFILTER']
137:               logger.info "skipping `#{task.fully_qualified_name}' because no servers matched"
138:               return
139:             else
140:               raise Capistrano::NoMatchingServersError, "`#{task.fully_qualified_name}' is only run for servers matching #{task.options.inspect}, but no servers matched"
141:             end
142:           end
143: 
144:           if task.continue_on_error?
145:             servers.delete_if { |s| has_failed?(s) }
146:             return if servers.empty?
147:           end
148:         else
149:           servers = find_servers(options)
150:           raise Capistrano::NoMatchingServersError, "no servers found to match #{options.inspect}" if servers.empty?
151:         end
152: 
153:         servers = [servers.first] if options[:once]
154:         logger.trace "servers: #{servers.map { |s| s.host }.inspect}"
155: 
156:         max_hosts = (options[:max_hosts] || (task && task.max_hosts) || servers.size).to_i
157:         is_subset = max_hosts < servers.size
158: 
159:         # establish connections to those servers in groups of max_hosts, as necessary
160:         servers.each_slice(max_hosts) do |servers_slice|
161:           begin
162:             establish_connections_to(servers_slice)
163:           rescue ConnectionError => error
164:             raise error unless task && task.continue_on_error?
165:             error.hosts.each do |h|
166:               servers_slice.delete(h)
167:               failed!(h)
168:             end
169:           end
170: 
171:           begin
172:             yield servers_slice
173:           rescue RemoteError => error
174:             raise error unless task && task.continue_on_error?
175:             error.hosts.each { |h| failed!(h) }
176:           end
177: 
178:           # if dealing with a subset (e.g., :max_hosts is less than the
179:           # number of servers available) teardown the subset of connections
180:           # that were just made, so that we can make room for the next subset.
181:           teardown_connections_to(servers_slice) if is_subset
182:         end
183:       end

Indicate that the given server could not be connected to.

[Source]

    # File lib/capistrano/configuration/connections.rb, line 66
66:       def failed!(server)
67:         Thread.current[:failed_sessions] << server
68:       end

Indicate that the given server could not be connected to.

[Source]

    # File lib/capistrano/configuration/connections.rb, line 66
66:       def failed!(server)
67:         Thread.current[:failed_sessions] << server
68:       end

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

[Source]

    # File lib/capistrano/configuration/connections.rb, line 72
72:       def has_failed?(server)
73:         Thread.current[:failed_sessions].include?(server)
74:       end

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

[Source]

    # File lib/capistrano/configuration/connections.rb, line 72
72:       def has_failed?(server)
73:         Thread.current[:failed_sessions].include?(server)
74:       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.

[Source]

    # File lib/capistrano/configuration/connections.rb, line 55
55:       def sessions
56:         Thread.current[:sessions] ||= {}
57:       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.

[Source]

    # File lib/capistrano/configuration/connections.rb, line 55
55:       def sessions
56:         Thread.current[:sessions] ||= {}
57:       end

Destroys sessions for each server in the list.

[Source]

     # File lib/capistrano/configuration/connections.rb, line 119
119:       def teardown_connections_to(servers)
120:         servers.each do |server|
121:           sessions[server].close
122:           sessions.delete(server)
123:         end
124:       end

Destroys sessions for each server in the list.

[Source]

     # File lib/capistrano/configuration/connections.rb, line 119
119:       def teardown_connections_to(servers)
120:         servers.each do |server|
121:           sessions[server].close
122:           sessions.delete(server)
123:         end
124:       end

[Validate]