Narnach-simple_gate 0.5.2 → 0.5.3

data/README.rdoc

@@ -50,6 +50,13 @@ connection.
 
 == Recent changes
 
+=== Version 0.5.3
+
+* Added yardoc documentation to all classes.
+* SimpleGate#through raises an error when no gates are chosen
+* SimpleGate#through uses local variables instead of instance variables
+* ServerDefinition#options is created on the fly
+
 === Version 0.5.2
 
 * Added -V verbose flag to gate_cp

data/lib/simple_gate/router.rb

@@ -1,25 +1,33 @@
 class Router
-  # Graph of server connections. 
-  # It's a Hash of Arrays, which contains strings. Keys are server names with
-  # a connection to other servers. Each of these servers is a string in the
-  # associated Array.
-  # An example graph with three servers 'foo', 'bar' and 'baz'.
+  # Graph of server connections.
+  attr_accessor :paths
+
+  # Create a new Router for a network of interconnected servers.
+  # An example connections graph with three servers 'foo', 'bar' and 'baz':
   #
   #   router = Router.new
+  #   # Define a graph: foo -> bar -> baz
   #   router.paths = {
   #     'foo' => %w[bar],
-  #     'bar' => ['baz']
+  #     'bar' => %w[baz]
   #   }
   #   router.find('foo', 'baz') #=> ['foo', 'bar', 'baz']
-  attr_accessor :paths
-
+  # @param [Hash] paths Graph of server connections.
+  #   It's a Hash of Arrays, which contains strings. Keys are server
+  #   names with a connection to other servers. Each of these servers is a
+  #   string in the associated Array.
   def initialize(paths={})
     @paths = paths
   end
 
-  # A simple pathfinder. Returns a route as Array or nil.
+  # A simple recursive pathfinder.
   # Uses a very naieve depth-first recursive full-graph search to
   # find the shortest route.
+  # @param [String] start The node to start searching from for +target+.
+  # @param [String] target The node to look for. Once it is found, return the shortest route to it.
+  # @param [Array] current_route Internal variable that holds the route so far. Helps in preventing cyclic routes from being checked an infinite amount of times.
+  # @return [Array] The sequence of nodes that connect +start+ to +target+.
+  # @return [nil] When no route was found.
   def find(start, target, current_route = [])
     return [target] if start == target
     return nil unless paths.has_key?(start)

data/lib/simple_gate/server_definition.rb

@@ -1,57 +1,72 @@
 require 'yaml'
 class ServerDefinition
-  attr_accessor :host, :user, :options, :port, :password
-  
+  attr_accessor :host, :user, :port, :password, :auth_methods
+
+  # Create a new ServerDefinition.
+  #
+  # @param [String] host Name of server.
+  # @param [Hash] options Override the server's own configuration.
+  # @option options [Integer] port (22) Server port
+  # @option options [String] user SSH user
+  # @option options [String] password SSH password
   def initialize(host, options = {})
-    @options = {:port => 22}.merge(options)
     self.host = host
-    self.user = @options[:user]
-    self.password = @options[:password]
-    self.port = @options[:port]
-  end
-  
-  def user=(user)
-    options[:user] = user
-    @user=user
-  end
-
-  def port=(port)
-    options[:port] = port
-    @port=port
+    self.user = options[:user]
+    self.password = options[:password]
+    self.port = options[:port] || 22
+    self.auth_methods = options[:auth_methods] || %w[password keyboard-interactive]
   end
 
-  def password=(password)
-    options[:password] = password
-    @password=password
+  # SSH options
+  # @return [Hash]
+  def options
+    {
+      :user => user,
+      :password => password,
+      :port => port,
+      :auth_methods => auth_methods
+    }
   end
 
+  # Yield connection information.
+  # @yieldparam [String] host SSH host
+  # @yieldparam [String] user SSH user
+  # @yieldparam [Hash] options SSH connection options
+  # @see ServerDefinition#initialize
+  # @see ServerDefinition#ssh_options
   def connection_info(&block)
-    block.call(host, user, options.merge(ssh_options))
+    block.call(host, user, options)
   end
-  
-  def ssh_options
-    {
-      :auth_methods => %w[password keyboard-interactive]
-    }
-  end
-  
+
+  # Represent server definition as URL-like string
+  # @return [String]
   def to_s
     "#{user}:#{'*' * password.to_s.size}@#{host}:#{port}"
   end
-  
+
+  # Factory method that uses pre-defined server configurations.
+  # @return [ServerDefinition]
   def self.lookup(server)
     server = servers[server]
-    new(server['address'],{ 
+    new(server['address'],{
       :user => server['username'],
-      :password => server['password'], 
+      :password => server['password'],
       :port => server['port']
     })
   end
-  
+
+  # Factory method that chooses between a lookup and parse.
+  # @param [String] server Server name or ssh string
+  # @return [ServerDefinition]
+  # @see ServerDefinition.lookup
+  # @see ServerDefinition.parse
   def self.find(server)
     servers.has_key?(server) ? lookup(server) : parse(server)
   end
-  
+
+  # Factory method that parses a connection string.
+  # @param [String] ssh_string String formatted as "user:password@host:port"
+  # @return [ServerDefinition]
   def self.parse(ssh_string)
     user, password, host, port = ssh_string.match /\A(.*?):(.*?)@(.*?):(\d*?)\Z/
     new(host, :user => user, :password => password, :port => port)
@@ -76,6 +91,7 @@ class ServerDefinition
     #
     # Since the parsed Hash of servers is cached, a value can be stored and
     # the configuration file ignored if desired.
+    # @return [Hash] Server name to server configuration pairs.
     def servers
       @servers ||= YAML.load_file(File.expand_path('~/.servers.yml'))
     end

data/lib/simple_gate.rb

@@ -5,19 +5,26 @@ require 'activesupport'
 require 'simple_gate/server_definition'
 
 class SimpleGate
+  # Initialize a new SimpleGate
+  # @param [Hash] options Hash with options to configure SimpleGate. Defaults to set :verbose to false.
   def initialize(options={})
     @options = {
       :verbose => false
     }.merge(options)
   end
 
+  # Is the verbose option turned on?
   def verbose?
     @options[:verbose]
   end
 
-  # Connect through a list of gateways to the real server.
-  # Treats the last 'gateway' as the real server and the others as gateways.
-  def through_to(*gateways) # :yields: ssh session
+  # Connect through a list of gateways to a target server.
+  # Treats the last 'gateway' as the target server and the others as gateways.
+  #
+  # @param [Array] *gateways A list of gateway server names that can be found using ServerDefinition.find(). Should have at least one server name.
+  # @yieldparam [Net::SSH::Connection::Session] session SSH Session to the target server.
+  # @raise [ArgumentError] When no gateways are chosen.
+  def through_to(*gateways)
     gateways = gateways.flatten
     raise ArgumentError.new("No target chosen") if gateways.size == 0
     target = ServerDefinition.find(gateways.pop)
@@ -39,19 +46,27 @@ class SimpleGate
     nil
   end
 
+  # Establish a series of gateways and yields the last one created.
+  # Will automatically shut down gateway connections when the block closes.
+  #
   # Most of the code was taken from Capistrano and then changed to work
   # outside of Capistrano.
+  #
+  # @param [Array] *gateways A list of gateway server names that can be found using ServerDefinition.find(). Should have at least one server name.
+  # @yieldparam [Net::SSH::Gateway] gateway Gateway object of the last tunnel endpoint.
+  # @raise [ArgumentError] When no gateways are chosen.
   def through(*gateways)
     Thread.abort_on_exception = true
-    @open_connections ||= []
-    @gateways = gateways.flatten.collect { |g| ServerDefinition.find(g) }
-    tunnel = @gateways[0].connection_info do |host, user, connect_options|
-      STDERR.puts "Setting up tunnel #{@gateways[0]}" if verbose?
+    open_connections = []
+    gateways = gateways.flatten.collect { |g| ServerDefinition.find(g) }
+    raise ArgumentError.new("No target chosen") if gateways.size == 0
+    tunnel = gateways[0].connection_info do |host, user, connect_options|
+      STDERR.puts "Setting up tunnel #{gateways[0]}" if verbose?
       gw = Net::SSH::Gateway.new(host, user, connect_options)
-      @open_connections << gw
+      open_connections << gw
       gw
     end
-    @gateway = (@gateways[1..-1]).inject(tunnel) do |tunnel, destination|
+    gateway = (gateways[1..-1]).inject(tunnel) do |tunnel, destination|
       STDERR.puts "Connecting to #{destination}" if verbose?
       tunnel_port = tunnel.open(destination.host, (destination.port || 22))
       localhost_options = {:user => destination.user, :port => tunnel_port, :password => destination.password}
@@ -59,13 +74,13 @@ class SimpleGate
       local_host.connection_info do |host, user, connect_options|
         STDERR.puts "Connecting using local info #{local_host}" if verbose?
         gw = Net::SSH::Gateway.new(host, user, connect_options)
-        @open_connections << gw
+        open_connections << gw
         gw
       end
     end
-    yield(@gateway)
+    yield(gateway)
   ensure
-    while g = @open_connections.pop
+    while g = open_connections.pop
       g.shutdown!
     end
   end

data/simple_gate.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
   s.name         = 'simple_gate'
   s.summary      = "SimpleGate makes it possible to use net/ssh/gateway's capabilities in a simple to use way."
   s.description  = s.summary
-  s.version      = '0.5.2'
-  s.date         = '2009-04-18'
+  s.version      = '0.5.3'
+  s.date         = '2009-05-16'
   s.platform     = Gem::Platform::RUBY
   s.authors      = ["Wes Oldenbeuving"]
   s.email        = "narnach@gmail.com"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: Narnach-simple_gate
 version: !ruby/object:Gem::Version 
-  version: 0.5.2
+  version: 0.5.3
 platform: ruby
 authors: 
 - Wes Oldenbeuving
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-18 00:00:00 -07:00
+date: 2009-05-16 00:00:00 -07:00
 default_executable: 
 dependencies: []