Module: Capistrano::Configuration::Connections

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

### Methods

connect! connect! connection_factory connection_factory establish_connections_to establish_connections_to execute_on_servers execute_on_servers failed! failed! has_failed? has_failed? sessions sessions teardown_connections_to teardown_connections_to

### Public Instance methods

connect!(options={})

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

connect!(options={})

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

connection_factory()

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

connection_factory()

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

establish_connections_to(servers)

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

establish_connections_to(servers)

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

execute_on_servers(options={}) {|servers_slice| ...}

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

execute_on_servers(options={}) {|servers_slice| ...}

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

failed!(server)

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

failed!(server)

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

has_failed?(server)

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

has_failed?(server)

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

sessions()

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

sessions()

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

teardown_connections_to(servers)

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

teardown_connections_to(servers)

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]