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:
- Array.<string>
(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. |