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

Methods

Attributes

sessions  [R]  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.
sessions  [R]  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.

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 78
78:       def connect!(options={})
79:         execute_on_servers(options) { }
80:       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 78
78:       def connect!(options={})
79:         execute_on_servers(options) { }
80:       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 85
85:       def connection_factory
86:         @connection_factory ||= begin
87:           if exists?(:gateway)
88:             logger.debug "establishing connection to gateway `#{fetch(:gateway)}'"
89:             GatewayConnectionFactory.new(fetch(:gateway), self)
90:           else
91:             DefaultConnectionFactory.new(self)
92:           end
93:         end
94:       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 85
85:       def connection_factory
86:         @connection_factory ||= begin
87:           if exists?(:gateway)
88:             logger.debug "establishing connection to gateway `#{fetch(:gateway)}'"
89:             GatewayConnectionFactory.new(fetch(:gateway), self)
90:           else
91:             DefaultConnectionFactory.new(self)
92:           end
93:         end
94:       end

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

[Source]

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

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

[Source]

     # File lib/capistrano/configuration/connections.rb, line 97
 97:       def establish_connections_to(servers)
 98:         failed_servers = []
 99: 
100:         # force the connection factory to be instantiated synchronously,
101:         # otherwise we wind up with multiple gateway instances, because
102:         # each connection is done in parallel.
103:         connection_factory
104: 
105:         threads = Array(servers).map { |server| establish_connection_to(server, failed_servers) }
106:         threads.each { |t| t.join }
107: 
108:         if failed_servers.any?
109:           errors = failed_servers.map { |h| "#{h[:server]} (#{h[:error].class}: #{h[:error].message})" }
110:           error = ConnectionError.new("connection failed for: #{errors.join(', ')}")
111:           error.hosts = failed_servers.map { |h| h[:server] }
112:           raise error
113:         end
114:       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 127
127:       def execute_on_servers(options={})
128:         raise ArgumentError, "expected a block" unless block_given?
129: 
130:         if task = current_task
131:           servers = find_servers_for_task(task, options)
132: 
133:           if servers.empty?
134:             if ENV['HOSTFILTER']
135:               logger.info "skipping `#{task.fully_qualified_name}' because no servers matched"
136:               return
137:             else
138:               raise Capistrano::NoMatchingServersError, "`#{task.fully_qualified_name}' is only run for servers matching #{task.options.inspect}, but no servers matched"
139:             end
140:           end
141: 
142:           if task.continue_on_error?
143:             servers.delete_if { |s| has_failed?(s) }
144:             return if servers.empty?
145:           end
146:         else
147:           servers = find_servers(options)
148:           raise Capistrano::NoMatchingServersError, "no servers found to match #{options.inspect}" if servers.empty?
149:         end
150: 
151:         servers = [servers.first] if options[:once]
152:         logger.trace "servers: #{servers.map { |s| s.host }.inspect}"
153: 
154:         max_hosts = (options[:max_hosts] || (task && task.max_hosts) || servers.size).to_i
155:         is_subset = max_hosts < servers.size
156: 
157:         # establish connections to those servers in groups of max_hosts, as necessary
158:         servers.each_slice(max_hosts) do |servers_slice|
159:           begin
160:             establish_connections_to(servers_slice)
161:           rescue ConnectionError => error
162:             raise error unless task && task.continue_on_error?
163:             error.hosts.each do |h|
164:               servers_slice.delete(h)
165:               failed!(h)
166:             end
167:           end
168: 
169:           begin
170:             yield servers_slice
171:           rescue RemoteError => error
172:             raise error unless task && task.continue_on_error?
173:             error.hosts.each { |h| failed!(h) }
174:           end
175: 
176:           # if dealing with a subset (e.g., :max_hosts is less than the
177:           # number of servers available) teardown the subset of connections
178:           # that were just made, so that we can make room for the next subset.
179:           teardown_connections_to(servers_slice) if is_subset
180:         end
181:       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 127
127:       def execute_on_servers(options={})
128:         raise ArgumentError, "expected a block" unless block_given?
129: 
130:         if task = current_task
131:           servers = find_servers_for_task(task, options)
132: 
133:           if servers.empty?
134:             if ENV['HOSTFILTER']
135:               logger.info "skipping `#{task.fully_qualified_name}' because no servers matched"
136:               return
137:             else
138:               raise Capistrano::NoMatchingServersError, "`#{task.fully_qualified_name}' is only run for servers matching #{task.options.inspect}, but no servers matched"
139:             end
140:           end
141: 
142:           if task.continue_on_error?
143:             servers.delete_if { |s| has_failed?(s) }
144:             return if servers.empty?
145:           end
146:         else
147:           servers = find_servers(options)
148:           raise Capistrano::NoMatchingServersError, "no servers found to match #{options.inspect}" if servers.empty?
149:         end
150: 
151:         servers = [servers.first] if options[:once]
152:         logger.trace "servers: #{servers.map { |s| s.host }.inspect}"
153: 
154:         max_hosts = (options[:max_hosts] || (task && task.max_hosts) || servers.size).to_i
155:         is_subset = max_hosts < servers.size
156: 
157:         # establish connections to those servers in groups of max_hosts, as necessary
158:         servers.each_slice(max_hosts) do |servers_slice|
159:           begin
160:             establish_connections_to(servers_slice)
161:           rescue ConnectionError => error
162:             raise error unless task && task.continue_on_error?
163:             error.hosts.each do |h|
164:               servers_slice.delete(h)
165:               failed!(h)
166:             end
167:           end
168: 
169:           begin
170:             yield servers_slice
171:           rescue RemoteError => error
172:             raise error unless task && task.continue_on_error?
173:             error.hosts.each { |h| failed!(h) }
174:           end
175: 
176:           # if dealing with a subset (e.g., :max_hosts is less than the
177:           # number of servers available) teardown the subset of connections
178:           # that were just made, so that we can make room for the next subset.
179:           teardown_connections_to(servers_slice) if is_subset
180:         end
181:       end

Indicate that the given server could not be connected to.

[Source]

    # File lib/capistrano/configuration/connections.rb, line 64
64:       def failed!(server)
65:         @failed_sessions << server
66:       end

Indicate that the given server could not be connected to.

[Source]

    # File lib/capistrano/configuration/connections.rb, line 64
64:       def failed!(server)
65:         @failed_sessions << server
66:       end

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

[Source]

    # File lib/capistrano/configuration/connections.rb, line 70
70:       def has_failed?(server)
71:         @failed_sessions.include?(server)
72:       end

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

[Source]

    # File lib/capistrano/configuration/connections.rb, line 70
70:       def has_failed?(server)
71:         @failed_sessions.include?(server)
72:       end

Destroys sessions for each server in the list.

[Source]

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

Destroys sessions for each server in the list.

[Source]

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

[Validate]