selenium_tor 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd34aa798531de8ada12d53163c343733610aa6115141d58aeaa3b4875c40cd6
-  data.tar.gz: f989c3ca02651ba825beefde17a4f2ac007ae25bb7c09e29ca080eee24cd3d03
+  metadata.gz: 99d3e4260b0873513c67db620d3057d61078b4c1cbae7b5c8c7b3e4cfdbbfbec
+  data.tar.gz: bb02cb9d07024a4798723185f4103246dac9b4c008e3f20abec5f710426a26a6
 SHA512:
-  metadata.gz: 1a71cffb60fc1e7f58d4a8cb4ffc9b0b42abfca1f5c541332b0febf50b78440fb5adfacb76f18e7289184bd7fb185582c4b338f6c2cde8177847b0db4e9a8ba7
-  data.tar.gz: 3c9291018aede2ef805bf96110ff3742b4e2791634801be4ac607ad27e4d318ddafe931950946499a8547883c48ca750d6af9a409674b91e40cf9cce41e418b5
+  metadata.gz: 654db110ca016a71d04b6def25d4befb86efc27cd2c0cce1ed7874834921d309262bc537b6b23bf8b77603b4d29960c88a10d83c8508ce6398b1d44a13577df1
+  data.tar.gz: 7d7369f8055ca42c229079d8732ab49d8d1467af49d35c547528dd792f1208101abcd123a6f05873b9fee4b704863a364708fc9148850f798635b9f3f6b3b8da

data/.rubocop.yml

@@ -27,3 +27,7 @@ Style/RegexpLiteral:
 
 Minitest/TestMethodName:
   Enabled: true
+
+Minitest/TestFileName:
+  Exclude:
+    - test/features/fingerprinting/vglrun_test_fingerprintjs.rb

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## master (unreleased)
 
+## [1.1.0] - 2024-07-28
+
+### Bug fixes
+
+* [#9](https://gitlab.com/matzfan/selenium-tor/-/issues/9)
+
+### New features
+
+* deprecate SystemTor options IFO tor_opts
+
 ## [1.0.0] - 2024-07-15
 
 ### New features

data/README.md

@@ -44,40 +44,36 @@ options = Selenium::WebDriver::Tor::Options.new
 @driver.title # => Congratulations. This browser is configured to use Tor.
 @driver.quit
 ```
-By default Tor Broswer will use the bundled `tor` process, in which case the driver will not be instantiated until a connection to the Tor network is made. If the network is inaccessible for any reason a `TorNetworkError` will result.
+If the network is inaccessible for any reason a `TorNetworkError` will result.
 
-### Multiple instances using the system tor
+### Multiple driver instances
 
-The following options require `tor` to be installed. Tor is available via various package managers e.g. `sudo apt install tor`.
-
-If a `SystemTor` object is passed to options, the system `tor` will be used instead of the `tor` included in the Tor Browser Bundle (TBB).
-```ruby
-system_tor = Selenium::WebDriver::Tor::SystemTor.new # writes a driver-specific torrc file
-options = Selenium::WebDriver::Tor::Options.new system_tor: system_tor
-@driver = Selenium::WebDriver.for :tor, options: options # new tor process started when :system_tor option passed to driver
-@driver.get 'https://example.com'
-@driver.quit # stops the new system tor process and deletes torrc file
-```
-Multiple instances may be instantiated, in which case `SystemTor` options for :socks_port (default 9150) and :control_port (default 9151) must be set for each so they do not conflict. For example:
+Running multiple `tor` processes requires that each uses different ports for SocksPort and ControlPort. These and other valid tor options can be passed using the `:tor_opts` key. Recognized options are snake_case equivalents of the camel case options reconized by tor. For a list see `man tor`. An example using the [Parallel gem](https://rubygems.org/gems/parallel):
 ```ruby
-def new_driver(socks_p, control_p)
-  system_tor = Selenium::WebDriver::Tor::SystemTor.new(socks_port: socks_p, control_port: control_p)
-  options = Selenium::WebDriver::Tor::Options.new system_tor: system_tor
-  Selenium::WebDriver.for :tor, options: options
-end
+require 'parallel'
 
 socks_port = 9150
 control_port = 9151
 
-driver1 = new_driver(socks_port, control_port)
-socks_port += 2
-control_port += 2
-driver2 = new_driver(socks_port, control_port)
+def driver(socks_p, control_p)
+  options = Selenium::WebDriver::Tor::Options.new tor_opts: { socks_port: socks_p, control_port: control_p }
+  Selenium::WebDriver.for :tor, options: options # new tor process started with tor_opts
+end
+
+driver1 = driver(socks_port, control_port)
+driver2 = driver(socks_port += 2, control_port += 2)
 
-driver1.quit
-driver2.quit
-```
+title = 'Congratulations. This browser is configured to use Tor.'
 
+Parallel.all?([driver1, driver2], in_threads: 2) do |driver|
+  driver.get 'https://check.torproject.org'
+  driver.title == title
+end
+# => true
+
+driver1&.quit
+driver2&.quit
+```
 The `Selenium::WebDriver::Tor` namespace is used for `Driver`, `Options`, `Profile` and all tor-specific classes. Otherwise Selenium's `Selenium::WebDriver::Firefox` namespace is used.
 
 Remote functionality is not tested, but may be if a suitable Tor Browser Docker container becomes available.

data/fonts/000_README.txt

@@ -0,0 +1,7 @@
+DO NOT MODIFY THE CONTENTS OF THIS DIRECTORY
+
+Any adjustment to bundled fonts will result in an altered fingerprint. Font
+fingerprinting is more than just detecting what fonts you have, it also includes
+font fallbacks and characters (unicode code points) and any change in those can
+be measured.
+

data/lib/tor/driver.rb

@@ -1,58 +1,55 @@
 # frozen_string_literal: true
 
 require 'open-uri'
-require_relative 'driver_not_yet_connected_to_tor_network'
+require_relative '../service'
+require_relative '../options'
+require_relative 'profile'
+require_relative 'tor_process'
 
 module Selenium
   module WebDriver
     module Tor
+      # delegate class so extensions can be added & connection to tor made
+      class DriverNotYetConnectedToTorNetwork < Firefox::Driver; end
+
       # tor driver
       class Driver < DelegateClass(DriverNotYetConnectedToTorNetwork)
         class TorNetworkError < StandardError; end
 
-        CONNECT_BUTTON_ID = 'network-status-tor-connect-button' # visible only until connected
-        TOR_PREFS_CONNECTION_URL = 'about:preferences#connection'
-
-        attr_reader :system_tor
-
         def initialize(options: nil, **)
-          instantiate_driver_from_tbb_dir(options: options, **)
-          setup_system_tor options.system_tor if options&.system_tor
+          @data_dir = Dir.mktmpdir
+          add_torrc_path_to_options options
+          @instance = DriverNotYetConnectedToTorNetwork.new(options: options, **)
           super(@instance)
-          install_extensions
-          wait_for_tor_connection unless system_tor # no need if system tor used
+          install_extensions(@instance)
+          create_tor_process_and_start_tor options&.tor_opts
+        end
+
+        def browser
+          :tor # overides :firefox
         end
 
         def quit
-          system_tor&.stop_tor
+          @tor_process&.stop_tor
+          FileUtils.rm_rf @data_dir
           super
         end
 
         private
 
-        def instantiate_driver_from_tbb_dir(...)
-          cwd = FileUtils.pwd
-          FileUtils.cd TBB_BROWSER_DIR # crucial - fixes [#2](https://gitlab.com/matzfan/selenium-tor/-/issues/2)
-          @instance = DriverNotYetConnectedToTorNetwork.new(...)
-        ensure
-          FileUtils.cd cwd
-        end
+        def add_torrc_path_to_options(options)
+          return unless options
 
-        def wait_for_tor_connection
-          @instance.get TOR_PREFS_CONNECTION_URL
-          Wait.new(timeout: 10).until { !@instance.find_element(:id, CONNECT_BUTTON_ID).displayed? }
-        rescue Selenium::WebDriver::Error::TimeoutError => e
-          @instance.quit # abort initialization
-          raise TorNetworkError, "Cannot connect to Tor network: #{e.message}"
+          options.prefs['extensions.torlauncher.torrc_path'] = File.join(@data_dir, 'torrc')
         end
 
-        def install_extensions
-          Pathname.new(TBB_EXTENSIONS_DIR).children.each { |xpi_path| @instance.install_addon xpi_path }
+        def install_extensions(instance)
+          Pathname.new(TBB_EXTENSIONS_DIR).children.each { |xpi_path| instance.install_addon xpi_path }
         end
 
-        def setup_system_tor(system_tor)
-          @system_tor = system_tor
-          system_tor.start_tor
+        def create_tor_process_and_start_tor(opts)
+          @tor_process = TorProcess.new(@data_dir, opts || {})
+          @tor_process.start_tor
         end
       end
     end

data/lib/tor/options.rb

@@ -9,44 +9,47 @@ module Selenium
     module Tor
       # tor options
       class Options < Firefox::Options
-        CAPABILITIES = CAPABILITIES.merge(system_tor: 'system_tor')
+        CAPABILITIES = CAPABILITIES.merge(tor_opts: 'tor_opts')
+        CAPABILITIES[:system_tor] = 'system_tor' # DEPRECATED 2.0
         DEFAULT_TBB_DIR = File.join Dir.home, 'tor-browser'
 
         Tor::TBB_DIR = ENV.fetch('TOR_BROWSER_ROOT_DIR', nil) || DEFAULT_TBB_DIR
         Tor::TBB_BROWSER_DIR = File.join Tor::TBB_DIR, 'Browser'
         Tor::TBB_BINARY_PATH = File.join Tor::TBB_BROWSER_DIR, 'firefox'
+        Tor::TBB_TOR_BINARY_PATH = File.join Tor::TBB_BROWSER_DIR, *%w[TorBrowser Tor tor]
         Tor::TBB_PROFILE_DIR = File.join Tor::TBB_BROWSER_DIR, *%w[TorBrowser Data Browser profile.default]
         Tor::TBB_EXTENSIONS_DIR = File.join Tor::TBB_PROFILE_DIR, 'extensions'
         Tor::TBB_VERSION = JSON.parse(File.read(File.join(Tor::TBB_BROWSER_DIR, 'tbb_version.json')))['version']
 
-        attr_reader :system_tor # read by Driver
+        attr_reader :tor_opts
 
         def initialize(log_level: nil, **opts)
-          @system_tor_prefs = {}
-          system_tor_prefs(opts.delete(:system_tor)) if opts[:system_tor] # must be deleted before call to super
+          opts[:tor_opts] = opts.delete(:system_tor).opts if opts[:system_tor] # DEPRECATED 2.0
+          @tor_opts = opts[:tor_opts] ? opts.delete(:tor_opts) : {} # must be deleted before call to super
           super(log_level: log_level, **tor_options(opts.delete(:prefs)).merge(opts))
           do_start_tor_browser_script_stuff # stuff the start-tor-browser script in TBB does
+          copy_fonts # so we don't have to change dir before executing TB binary #2 and #9
         end
 
         private
 
-        def system_tor_prefs(system_tor)
-          @system_tor = system_tor
-          @system_tor_prefs = system_tor.prefs
-        end
-
         def tor_options(prefs)
-          { binary: TBB_BINARY_PATH, prefs: (prefs || {}).merge(TOR_PREFS).merge(@system_tor_prefs) }
+          { binary: TBB_BINARY_PATH, prefs: (prefs || {}).merge(TOR_PREFS) }
         end
 
         def do_start_tor_browser_script_stuff
           ENV['SESSION_MANAGER'] = nil
           ENV['XAUTHORITY'] = File.join(Dir.home, '.Xauthority') unless ENV.fetch('XAUTHORITY', nil)
-          ENV['FONTCONFIG_PATH'] = File.join Tor::TBB_BROWSER_DIR, 'fontconfig' # supposed to stop font leaks..
+          ENV['FONTCONFIG_PATH'] = File.join TBB_BROWSER_DIR, 'fontconfig'
           ENV['FONTCONFIG_FILE'] = 'fonts.conf'
           FileUtils.rm_rf File.join(Tor::TBB_BROWSER_DIR, *%w[TorBrowser Data fontconfig])
           ENV['GSETTINGS_BACKEND'] = 'memory'
-          # cd to TBB_BROWSER_DIR now handled in Tor::Driver
+        end
+
+        def copy_fonts
+          return unless Dir[File.join('fonts', '*')].size == 1 # README checked into git
+
+          FileUtils.cp(Dir[File.join(Tor::TBB_BROWSER_DIR, 'fonts', '*')], File.expand_path('fonts'))
         end
       end
     end

data/lib/tor/system_tor.rb

@@ -1,82 +1,15 @@
 # frozen_string_literal: true
 
-require 'timeout'
-require_relative 'torrc'
-require_relative '../string_extensions'
-
 module Selenium
   module WebDriver
     module Tor
-      # Respresentation of a system tor process
+      # DEPRECATED
       class SystemTor
-        include StringExtensions
-
-        class SystemTorError < StandardError; end
-
-        BOOTSTRAP_SUCCESS_REGEX = /Bootstrapped 100% \(done\): Done$/
-        BOOTSTRAP_FAIL_REGEX = /^[A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2}\.\d{3} \[err\] .*/
-        # BOOTSTRAP_TIMEOUT_REGEX = /^[A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2}\.\d{3} \[err\] .*/
-
-        TORRC_PREFS = { 'extensions.torlauncher.start_tor' => false }.freeze
-        TORRC_PATH_KEY = 'extensions.torlauncher.torrc_path'
-
-        attr_reader :pid, :config
+        attr_reader :opts
 
         def initialize(opts = {})
-          raise SystemTorError, 'tor executable not found in PATH' unless tor_executable?
-          raise ArgumentError, 'SystemTor.new takes an options hash' unless opts.is_a? Hash
-
-          @opts = map_opts_to_torrc_keys opts
-          @data_dir = Dir.mktmpdir # each tor process needs a separate data directory
-          @torrc = Torrc.new(@data_dir)
-          @config ||= setup_config # Hash to store torrc config
-        end
-
-        def prefs
-          TORRC_PREFS.merge({ TORRC_PATH_KEY => @torrc.path })
-        end
-
-        def start_tor
-          r, io = IO.pipe
-          pid = Process.spawn "tor -f #{@torrc.path}", out: io, err: :out
-          io.close
-          errors = parse_tor_bootstrap_errors r
-          errors.empty? ? @pid = pid : raise(SystemTorError, "Tor failed to start with errors:\n\n#{errors}")
-        ensure
-          r.close
-        end
-
-        def stop_tor
-          Process.kill 'KILL', pid if pid
-          FileUtils.rm_rf @data_dir if @data_dir
-          @pid = nil
-        end
-
-        private
-
-        def map_opts_to_torrc_keys(opts)
-          raise SystemTorError, 'Options hash keys must be snake case' unless opts.keys.map!(&:to_s).all?(&:snake_case?)
-
-          opts.transform_keys { |k| k.to_s.split('_').map(&:capitalize).join }
-        end
-
-        def setup_config
-          @torrc.write_to_config @opts
-          @torrc.config
-        end
-
-        def tor_executable?
-          `which tor`
-        end
-
-        def parse_tor_bootstrap_errors(io)
-          lines = []
-          io.each_line do |line|
-            lines << line
-            break lines if line.match BOOTSTRAP_FAIL_REGEX
-            break [] if line.match BOOTSTRAP_SUCCESS_REGEX
-            # break false if line.match BOOTSTRAP_TIMEOUT_REGEX
-          end
+          warn '[DEPRECATION] `SystemTor` options are deprecated in `selenium_tor` 2.0. Use `tor_opts` instead.'
+          @opts = opts
         end
       end
     end

data/lib/tor/tor_prefs.rb

@@ -17,7 +17,8 @@ module Selenium
 
       OTHER_PREFS = {
         'intl.language_notification.shown' => true, # affects font fingerprint (viewport size)
-        'remote.active-protocols' => 3 # CDP & BiDi future support
+        'remote.active-protocols' => 3, # CDP & BiDi future support
+        'extensions.torlauncher.start_tor' => false
       }.freeze
 
       TOR_PREFS = FIRST_CONNECTION_PREFS.merge OTHER_PREFS

data/lib/tor/tor_process.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'timeout'
+require_relative 'torrc'
+require_relative '../string_extensions'
+
+module Selenium
+  module WebDriver
+    module Tor
+      # Respresentation of a tor process
+      class TorProcess
+        include StringExtensions
+
+        class TorProcessError < StandardError; end
+
+        BOOTSTRAP_SUCCESS_REGEX = /Bootstrapped 100% \(done\): Done$/
+        BOOTSTRAP_FAIL_REGEX = /^[A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2}\.\d{3} \[err\] .*/
+        # BOOTSTRAP_TIMEOUT_REGEX = /^[A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2}\.\d{3} \[err\] .*/
+
+        attr_reader :pid, :config
+
+        def initialize(data_dir, opts = {})
+          valid_data_dir?(data_dir)
+          raise ArgumentError, 'TorProcess.new takes an options hash' unless opts.is_a? Hash
+
+          @data_dir = data_dir # each tor process needs a separate data directory
+          @opts = map_opts_to_torrc_keys opts
+          @torrc = Torrc.new(@data_dir)
+          @config ||= setup_config # Hash to store torrc config
+        end
+
+        def start_tor
+          r, io = IO.pipe
+          pid = Process.spawn "#{TBB_TOR_BINARY_PATH} -f #{@torrc.path}", out: io, err: :out
+          io.close
+          errors = parse_tor_bootstrap_errors r
+          errors.empty? ? @pid = pid : raise(TorProcessError, "Tor failed to start with errors:\n\n#{errors}")
+        ensure
+          r.close
+        end
+
+        def stop_tor
+          Process.kill 'KILL', pid if pid
+          FileUtils.rm_rf @data_dir if @data_dir
+          @pid = nil
+        end
+
+        # private
+
+        def valid_data_dir?(dir)
+          msg = 'data_dir must exist and be a dir'
+          raise ArgumentError, msg unless Pathname.new(dir.to_s).directory? && Pathname.new(dir.to_s).empty?
+        end
+
+        def map_opts_to_torrc_keys(opts)
+          raise TorProcessError, 'Options keys must be snake case' unless opts.keys.map!(&:to_s).all?(&:snake_case?)
+
+          opts.transform_keys { |k| k.to_s.split('_').map(&:capitalize).join }
+        end
+
+        def setup_config
+          @torrc.write_to_config @opts
+          @torrc.config
+        end
+
+        def parse_tor_bootstrap_errors(io)
+          lines = []
+          io.each_line do |line|
+            lines << line
+            break lines.join if line.match BOOTSTRAP_FAIL_REGEX
+            break '' if line.match BOOTSTRAP_SUCCESS_REGEX
+            # break false if line.match BOOTSTRAP_TIMEOUT_REGEX
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tor/torrc.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'options' # for Tor::TBB_TOR_BINARY_PATH
+
 module Selenium
   module WebDriver
     module Tor
@@ -41,7 +43,7 @@ module Selenium
           tmp = Tempfile.new
           tmp.write hash_to_config_string(hash)
           tmp.rewind
-          invalid_opts = parse_invalid_opts `tor -f #{tmp.path} --verify-config`
+          invalid_opts = parse_invalid_opts `#{TBB_TOR_BINARY_PATH} -f #{tmp.path} --verify-config`
           raise TorrcError, "Invalid torrc opts: #{invalid_opts}" unless invalid_opts.empty?
         ensure
           tmp.unlink

data/lib/tor/version.rb

@@ -3,7 +3,7 @@
 module Selenium
   module WebDriver
     module Tor
-      VERSION = '1.0.0'
+      VERSION = '1.1.0'
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: selenium_tor
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - MatzFan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-15 00:00:00.000000000 Z
+date: 2024-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
@@ -39,17 +39,18 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- fonts/000_README.txt
 - lib/driver.rb
 - lib/options.rb
 - lib/selenium_tor.rb
 - lib/service.rb
 - lib/string_extensions.rb
 - lib/tor/driver.rb
-- lib/tor/driver_not_yet_connected_to_tor_network.rb
 - lib/tor/options.rb
 - lib/tor/profile.rb
 - lib/tor/system_tor.rb
 - lib/tor/tor_prefs.rb
+- lib/tor/tor_process.rb
 - lib/tor/torrc.rb
 - lib/tor/version.rb
 - selenium_tor.gemspec
@@ -77,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.15
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Selenium extension for Tor Browser

data/lib/tor/driver_not_yet_connected_to_tor_network.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../service'
-require_relative '../options'
-require_relative '../tor/profile'
-
-module Selenium
-  module WebDriver
-    module Tor
-      # subclass - doesn't wait to be connected to tor network
-      class DriverNotYetConnectedToTorNetwork < Firefox::Driver
-        def browser
-          :tor # overides :firefox
-        end
-      end
-    end
-  end
-end