TorPool

TorPool

Class that represents a pool of Tor processes.

Constructor

new TorPool(tor_path, default_configopt, data_directory, load_balance_method, granax_optionsopt, loggeropt)

Source:
Creates an instance of `TorPool`.
Parameters:
Name Type Attributes Description
tor_path string Path to the Tor executable.
default_config Object | function <optional>
 Default configuration that will be passed to all Tor instances created. Can be a function. See Tor Documentation for all possible options
data_directory string Parent directory for the data directory of each proccess.
load_balance_method string Name of the load balance method to use. See TorPool#load_balance_methods.
granax_options string <optional>
 Object containing options that will be passed to granax for each instance.
logger string <optional>
 A winston logger. If not provided no logging will occur.

Extends

  • EventEmitter

Members

(static, readonly) load_balance_methods :function

Source:
Returns an enumeration of load balance methods as functions
Type:
  • function

data_directory :string

Source:
Parent directory for the data directory of each proccess.
Type:
  • string

default_tor_config :Object|function

Source:
Getter
Type:
  • Object | function

default_tor_config

Source:
Setter

granax_options :Logger

Source:
Object containing options that will be passed to granax for each instance.
Type:
  • Logger

(readonly) group_names :Set.<string>

Source:
Returns a Set containing the names of all of the groups.
Type:
  • Set.<string>

(readonly) groups :InstanceGroupCollection

Source:
Represents all groups currently in the pool.
Type:

(readonly) instance_names :Array.<string>

Source:
An array containing the names of the instances in the pool.
Type:

(readonly) instances :Array.<TorProcess>

Source:
An array containing all instances in the pool.
Type:

load_balance_method :string

Source:
Name of the load balance method to use.
Type:
  • string

logger :Logger

Source:
The winston logger.
Type:
  • Logger

tor_path :string

Source:
Path to the Tor executable.
Type:
  • string

Methods

(async) add(instance_definitions) → {Promise.<Array.<TorProcess>>}

Source:
Adds one or more instances to the pool from an array of definitions or single definition.
Parameters:
Name Type Description
instance_definitions Array.<InstanceDefinition> | InstanceDefinition
Throws:
If `instance_definitions` is falsy.
Returns:
Type
Promise.<Array.<TorProcess>>

add_instance_to_group(group, instance)

Source:
Adds an instance to a group. If the group doesn't exist it will be created.
Parameters:
Name Type Description
group string The group to add the instance to.
instance TorProcess The instance in question.

add_instance_to_group_at(group, instance_index)

Source:
Adds an instance to a group by the index of the instance in the pool. If the group doesn't exist it will be created.
Parameters:
Name Type Description
group string The group to add the instance to.
instance_index number The index of the instance in question.
Throws:
If an instance with the index provided does not exist.

add_instance_to_group_by_name(group, instance_name)

Source:
Adds an instance to a group by the TorProcess#instance_name property on the instance. If the group doesn't exist it will be created.
Parameters:
Name Type Description
group string The group to add the instance to.
instance_name string The name of the instance in question.
Throws:
If an instance with the name provided does not exist

(async) create(instance_definitions) → {Promise.<Array.<TorProcess>>}

Source:
Creates one or more instances to the pool from either an array of definitions, a single definition or a number. If a number is provided it will create n instances with empty definitions (e.g. `TorPool.create(5)` will create 5 instances).
Parameters:
Name Type Description
instance_definitions Array.<InstanceDefinition> | InstanceDefinition | number
Throws:
If `instances` is falsy.
Returns:
Type
Promise.<Array.<TorProcess>>

(async) create_instance(instance_definitionopt) → {Promise.<TorProcess>}

Source:
Creates an instance then adds it to the pool from the provided definiton. Instance will be added (and Promise will resolve) after the instance is fully bootstrapped.
Parameters:
Name Type Attributes Default Description
instance_definition InstanceDefinition <optional>
 {} Instance definition that will be used to create the instance.
Throws:
If an instance with the same InstanceDefinition#Name already exists.
Returns:
- The instance that was created.
Type
Promise.<TorProcess>

(async) exit() → {Promise}

Source:
Kills the Tor processes of all instances in the pool.
Returns:
- Resolves when all instances have been killed.
Type
Promise

(async) get_config_at(index, keyword) → {Promise.<Array.<string>>}

Source:
Get a configuration value from the instance at the index in the pool via the control protocol.
Parameters:
Name Type Description
index number Index of the instance in the pool.
keyword string Name of the configuration property.
Throws:
When no instance exists at the provided index.
Returns:
- The configuration property's value.
Type
Promise.<Array.<string>>

(async) get_config_by_name(name, keyword) → {Promise.<Array.<string>>}

Source:
Get a configuration value from the instance whose TorProcess.instance_name matches the provided name via the control protocol.
Parameters:
Name Type Description
name string Name of the instance.
keyword string Name of the configuration property.
Throws:
When no instance matched the provided name.
Returns:
- The configuration property's value.
Type
Promise.<Array.<string>>

instance_at(index) → {TorProcess}

Source:
Returns the instance located at the provided index in the pool. Is equivalent to `TorPool#instances[index]`
Parameters:
Name Type Description
index number Index of the instance in the pool
Returns:
- Matching instance
Type
TorProcess

instance_by_name(name) → {TorProcess}

Source:
Searches for an instance with the matching TorProcess#instance_name property.
Parameters:
Name Type Description
name string Name of the instance to search for
Returns:
- Matching instance
Type
TorProcess

instances_by_group(group_name) → {Array.<string>}

Source:
Returns an array containing all of the instances in a group.
Parameters:
Name Type Description
group_name string The group to query.
Throws:
If the provided group does not exist
Returns:
Type
Array.<string>

(async) new_identites() → {Promise}

Source:
Gets new identities for all instances in the pool.
Returns:
- Resolves when all instances have new identities.
Type
Promise

(async) new_identites_by_group(group) → {Promise}

Source:
Gets new identities for all instances in a group.
Parameters:
Name Type Description
group string Name of the group.
Returns:
- Resolves when all instances in the group have new identities.
Type
Promise

(async) new_identity_at(index) → {Promise}

Source:
Gets a new identity for the instance at the provided index in the pool.
Parameters:
Name Type Description
index number Index of the instance in the pool.
Returns:
- Resolves when the instance has a new identity.
Type
Promise

(async) new_identity_by_name(name) → {Promise}

Source:
Gets a new identity for the instance whose TorProcess.instance_name matches the provided name.
Parameters:
Name Type Description
name string Name of the instance.
Throws:
When no instance matched the provided name.
Returns:
- Resolves when the instance has a new identity.
Type
Promise

next() → {TorProcess}

Source:
Runs the load balance function (TorPool#load_balance_method) on the array of instances in the pool and returns the first instance in the array.
Returns:
- The first instance in the modified array.
Type
TorProcess

next_by_group(group) → {TorProcess}

Source:
To Do:
  • Load balance methods other than "round_robin" to be used
Rotates the array containing instances in the group provided so that the second element becomes the first element and the first element becomes the last element. [1,2,3] -> [2,3,1]
Parameters:
Name Type Description
group string Name of the group
Returns:
- The first element in the modified array
Type
TorProcess

(async) remove(instances, start_atopt) → {Promise}

Source:
Removes a number of instances from the pool and kills their Tor processes.
Parameters:
Name Type Attributes Default Description
instances number Number of instances to remove
start_at number <optional>
 0 Index to start removing from
Returns:
- Promise will resolve when the processes are dead
Type
Promise

(async) remove_at(instance_index) → {Promise}

Source:
Removes an instance at the provided index and kills its Tor process.
Parameters:
Name Type Description
instance_index number Index of the instance to remove
Returns:
- Promise will resolve when the process is dead
Type
Promise

(async) remove_by_name(instance_name) → {Promise}

Source:
Removes an instance whose TorProcess#instance_name property matches the provided name and kills its Tor process.
Parameters:
Name Type Description
instance_name string Name of the instance to remove
Returns:
- Promise will resolve when the process is dead
Type
Promise

remove_instance_from_group(group, instance)

Source:
Removes an instance from a group.
Parameters:
Name Type Description
group string The group to remove the instance from.
instance TorProcess The instance in question.

remove_instance_from_group_at(group, instance_index)

Source:
Removes an instance from a group by the index of the instance in the pool.
Parameters:
Name Type Description
group string The group to remove the instance from.
instance_index number The index of the instance in question.
Throws:
If an instance with the index provided does not exist.

remove_instance_from_group_by_name(group, instance_name)

Source:
Removes an instance from a group by the TorProcess#instance_name property on the instance.
Parameters:
Name Type Description
group string The group to remove the instance from.
instance_name string The name of the instance in question.
Throws:
If an instance with the name provided does not exist.

(async) set_config_all(keyword, value) → {Promise}

Source:
Set a configuration value for all instances in the pool via the control protocol.
Parameters:
Name Type Description
keyword string Name of the configuration property.
value any Value to set the configuration property to.
Returns:
Type
Promise

(async) set_config_at(index, keyword, value) → {Promise}

Source:
Set a configuration value for the instance at the index in the pool via the control protocol.
Parameters:
Name Type Description
index number Index of the instance in the pool.
keyword string Name of the configuration property.
value any Value to set the configuration property to.
Throws:
When no instance exists at the provided index.
Returns:
Type
Promise

(async) set_config_by_group(group, keyword, value) → {Promise}

Source:
Set a configuration value for all instances in the provided group via the control protocol.
Parameters:
Name Type Description
group string Name of the group.
keyword string Name of the configuration property.
value any Value to set the configuration property to.
Throws:
When the provided group does not exist.
Returns:
Type
Promise

(async) set_config_by_name(name, keyword, value) → {Promise}

Source:
Set a configuration value for the instance whose TorProcess.instance_name matches the provided name via the control protocol.
Parameters:
Name Type Description
name string Name of the instance.
keyword string Name of the configuration property.
value any Value to set the configuration property to.
Throws:
When no instance matched the provided name.
Returns:
Type
Promise

(async) signal_all(signal) → {Promise}

Source:
Send a signal via the control protocol to all instances in the pool.
Parameters:
Name Type Description
signal string The signal to send.
Returns:
Type
Promise

(async) signal_at(index, signal) → {Promise}

Source:
Send a signal via the control protocol to an instance at the provided index in the pool.
Parameters:
Name Type Description
index number Index of the instance in the pool.
signal string The signal to send.
Returns:
Type
Promise

(async) signal_by_group(group, signal) → {Promise}

Source:
Send a signal via the control protocol to all instances in the provided group.
Parameters:
Name Type Description
group string Name of the group.
signal string The signal to send.
Throws:
When the provided group does not exist.
Returns:
Type
Promise

(async) signal_by_name(name, signal) → {Promise}

Source:
Send a signal via the control protocol to an instance whose TorProcess#instance_name property matches the provided name.
Parameters:
Name Type Description
name string Name of the instance.
signal string The signal to send.
Returns:
Type
Promise

Events

instance_created

Source:
Fires when an instance has been created.
Type:
Parameters:
Name Type Description
instance TorProcess The instance that was created.