tor 0.1.1 → 0.1.2

data/README

@@ -10,10 +10,13 @@ Features
 
 * Supports checking whether Tor is installed in the user's current `PATH`,
   and if it is, returning the version number.
+* Supports parsing Tor configuration files and looking up the values of
+  particular options.
 * Supports querying and controlling a locally-running Tor process using the
   [Tor Control Protocol (TC)][TC] over a socket connection.
 * Supports querying the [Tor DNS Exit List (DNSEL)][TorDNSEL] to determine
   whether a particular host is a Tor exit node or not.
+* Compatible with Ruby 1.8.7+, Ruby 1.9.x, and JRuby 1.4/1.5.
 
 Examples
 --------
@@ -26,7 +29,22 @@ Examples
     Tor.available?                                     #=> true
     Tor.version                                        #=> "0.2.1.25"
 
-### Obtaining information about a running Tor process
+### Parsing the Tor configuration file (1)
+
+    torrc = Tor::Config.load("/etc/tor/torrc")
+
+### Parsing the Tor configuration file (2)
+
+    Tor::Config.open("/etc/tor/torrc") do |torrc|
+      puts "Tor SOCKS port: #{torrc['SocksPort']}"
+      puts "Tor control port: #{torrc['ControlPort']}"
+      puts "Tor exit policy:"
+      torrc.each('ExitPolicy') do |key, value|
+        puts "  #{value}"
+      end
+    end
+
+### Communicating with a running Tor process
 
     Tor::Controller.connect(:port => 9051) do |tor|
       puts "Tor version: #{tor.version}"
@@ -47,6 +65,7 @@ Dependencies
 ------------
 
 * [Ruby](http://ruby-lang.org/) (>= 1.8.7) or (>= 1.8.1 with [Backports][])
+* [Tor](https://www.torproject.org/download.html.en) (>= 0.2.1)
 
 Installation
 ------------

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2

data/lib/tor.rb

@@ -17,10 +17,33 @@ end
 ##
 # @see https://www.torproject.org/
 module Tor
+  autoload :Config,     'tor/config'
   autoload :Controller, 'tor/control'
   autoload :DNSEL,      'tor/dnsel'
   autoload :VERSION,    'tor/version'
 
+  ##
+  # Returns `true` if the Tor process is running locally, `false` otherwise.
+  #
+  # This works by attempting to establish a Tor Control Protocol (TC)
+  # connection to the standard control port 9051 on `localhost`. If Tor
+  # hasn't been configured with the `ControlPort 9051` option, this will
+  # return `false`.
+  #
+  # @example
+  #   Tor.running?      #=> false
+  #
+  # @return [Boolean]
+  # @since  0.1.2
+  def self.running?
+    begin
+      Tor::Controller.new.quit
+      true
+    rescue Errno::ECONNREFUSED
+      false
+    end
+  end
+
   ##
   # Returns `true` if Tor is available, `false` otherwise.
   #

data/lib/tor/config.rb

@@ -0,0 +1,103 @@
+module Tor
+  ##
+  # Tor configuration.
+  #
+  # @example Parsing a Tor configuration file (1)
+  #   torrc = Tor::Config.load("/etc/tor/torrc")
+  #
+  # @example Parsing a Tor configuration file (2)
+  #   Tor::Config.open("/etc/tor/torrc") do |torrc|
+  #     puts "Tor SOCKS port: #{torrc['SocksPort']}"
+  #     puts "Tor control port: #{torrc['ControlPort']}"
+  #     puts "Tor exit policy:"
+  #     torrc.each('ExitPolicy') do |key, value|
+  #       puts "  #{value}"
+  #     end
+  #   end
+  #
+  # @see   https://www.torproject.org/tor-manual.html.en
+  # @since 0.1.2
+  class Config
+    CONFDIR = '/etc/tor' unless defined?(CONFDIR)
+
+    ##
+    # Opens a Tor configuration file.
+    #
+    # @param  [String, #to_s]          filename
+    # @param  [Hash{Symbol => Object}] options
+    # @yield  [config]
+    # @yieldparam [Config] config
+    # @return [Config]
+    def self.open(filename, options = {}, &block)
+      if block_given?
+        block.call(self.load(filename, options))
+      else
+        self.load(filename, options)
+      end
+    end
+
+    ##
+    # Loads the configuration options from a Tor configuration file.
+    #
+    # @param  [String, #to_s]          filename
+    # @param  [Hash{Symbol => Object}] options
+    # @return [Config]
+    def self.load(filename, options = {})
+      self.new(options) do |config|
+        File.open(filename.to_s, 'rb') do |file|
+          file.each_line do |line|
+            case line = line.strip.chomp.strip
+              when ''   then next # skip empty lines
+              when /^#/ then next # skip comments
+              else line = line.split('#').first.strip
+            end
+            # TODO: support for unquoting and unescaping values
+            config << line.split(/\s+/, 2)
+          end
+        end
+      end
+    end
+
+    ##
+    # @param  [Hash{Symbol => Object}] options
+    # @yield  [config]
+    # @yieldparam [Config] config
+    def initialize(options = {}, &block)
+      @lines, @options = [], options.dup
+      block.call(self) if block_given?
+    end
+
+    ##
+    # Appends a new configuration option.
+    #
+    # @param  [Array(String, String)]
+    # @return [Config]
+    def <<(kv)
+      @lines << kv
+      self
+    end
+
+    ##
+    # Looks up the last value of a particular configuration option.
+    #
+    # @param  [String, Regexp] key
+    # @return [String]
+    def [](key)
+      values = each(key).map(&:last)
+      values.empty? ? nil : values.last
+    end
+
+    ##
+    # Enumerates configuration options.
+    #
+    # @param  [String, Regexp] key
+    # @yield  [key, value]
+    # @yieldparam [String] key
+    # @yieldparam [String] value
+    # @return [Enumerator]
+    def each(key = nil, &block)
+      return enum_for(:each, key) unless block_given?
+      key ? @lines.find_all { |k, v| key === k }.each(&block) : @lines.each(&block)
+    end
+  end
+end

data/lib/tor/control.rb

@@ -82,9 +82,9 @@ module Tor
     # Returns `true` if the controller connection is active.
     #
     # @example
-    #   tor.connected?      #=> true
+    #   tor.connected?             #=> true
     #   tor.close
-    #   tor.connected?      #=> false
+    #   tor.connected?             #=> false
     #
     # @return [Boolean]
     def connected?
@@ -119,19 +119,57 @@ module Tor
     #
     # @return [void]
     def quit
-      send_command(:quit)
+      send_line('QUIT')
       reply = read_reply
       close
       reply
     end
 
+    ##
+    # Returns information about the authentication method required by the
+    # Tor process.
+    #
+    # This command may be used before authenticating.
+    #
+    # @example
+    #     C: PROTOCOLINFO
+    #     S: 250-PROTOCOLINFO 1
+    #     S: 250-AUTH METHODS=NULL
+    #     S: 250-VERSION Tor="0.2.1.25"
+    #     S: 250 OK
+    #
+    # @example
+    #   tor.authentication_method  #=> nil
+    #   tor.authentication_method  #=> :hashedpassword
+    #   tor.authentication_method  #=> :cookie
+    #
+    # @return [Symbol]
+    # @since  0.1.2
+    def authentication_method
+      @authentication_method ||= begin
+        method = nil
+        send_line('PROTOCOLINFO')
+        loop do
+          # TODO: support for reading multiple authentication methods
+          case reply = read_reply
+            when /^250-AUTH METHODS=(\w*)/
+              method = $1.strip.downcase.to_sym
+              method = method.eql?(:null) ? nil : method
+            when /^250-/  then next
+            when '250 OK' then break
+          end
+        end
+        method
+      end
+    end
+
     ##
     # Returns `true` if the controller connection has been authenticated.
     #
     # @example
-    #   tor.authenticated?  #=> false
+    #   tor.authenticated?         #=> false
     #   tor.authenticate
-    #   tor.authenticated?  #=> true
+    #   tor.authenticated?         #=> true
     #
     # @return [Boolean]
     def authenticated?
@@ -169,7 +207,7 @@ module Tor
     #   S: 250 OK
     #
     # @example
-    #   tor.version         #=> "0.2.1.25"
+    #   tor.version                #=> "0.2.1.25"
     #
     # @return [String]
     def version
@@ -188,7 +226,7 @@ module Tor
     #   S: 250 OK
     #
     # @example
-    #   tor.config_file     #=> #<Pathname:/opt/local/etc/tor/torrc>
+    #   tor.config_file            #=> #<Pathname:/opt/local/etc/tor/torrc>
     #
     # @return [Pathname]
     def config_file

data/lib/tor/version.rb

@@ -2,7 +2,7 @@ module Tor
   module VERSION
     MAJOR = 0
     MINOR = 1
-    TINY  = 1
+    TINY  = 2
     EXTRA = nil
 
     STRING = [MAJOR, MINOR, TINY, EXTRA].compact.join('.')

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Arto Bendiken
@@ -59,6 +59,7 @@ files:
 - README
 - UNLICENSE
 - VERSION
+- lib/tor/config.rb
 - lib/tor/control.rb
 - lib/tor/dnsel.rb
 - lib/tor/version.rb