Usage

This section explains how to use the V2ROOT library to manage V2Ray proxy operations, with examples for common tasks.

Getting Started

First, import the V2ROOT class and create an instance. You can specify custom HTTP and SOCKS ports if needed:

from v2root import V2ROOT

# Initialize with default ports (HTTP: 2300, SOCKS: 2301)
client = V2ROOT()

# Or specify custom ports
client = V2ROOT(http_port=8080, socks_port=1080)

Starting the V2Ray Proxy

To start the V2Ray proxy service, use the start method. On Linux, this will also display instructions for setting proxy environment variables.

pid = client.start()
print(f"V2Ray started with PID: {pid}")

On Linux, you’ll need to manually set the proxy environment variables as shown in the terminal output:

export http_proxy=http://127.0.0.1:2300
export https_proxy=http://127.0.0.1:2300
export HTTP_PROXY=http://127.0.0.1:2300
export HTTPS_PROXY=http://127.0.0.1:2300
export socks_proxy=socks5://127.0.0.1:2301
export SOCKS_PROXY=socks5://127.0.0.1:2301

Stopping the V2Ray Proxy

To stop the V2Ray proxy service, use the stop method:

client.stop()
print("V2Ray stopped successfully!")

On Linux, you’ll need to unset the proxy environment variables:

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY socks_proxy SOCKS_PROXY

Setting a V2Ray Configuration

You can set a V2Ray configuration string (e.g., VLESS or VMess) using the set_config_string method:

config = "vless://user-id@server:443?security=tls&type=tcp#MyVLESS"
client.set_config_string(config)
print("Configuration set successfully!")

Testing a Configuration

To test the connectivity and latency of a V2Ray configuration, use the test_connection method:

config = "vless://user-id@server:443?security=tls&type=tcp#MyVLESS"
latency = client.test_connection(config)
print(f"Latency: {latency}ms")

Pinging a Server

To measure the latency to a specific server, use the ping_server method:

latency = client.ping_server("example.com", 443)
print(f"Ping latency: {latency}ms")

Testing Multiple Configurations

You can test multiple V2Ray configurations from a file or list and save the valid ones to a file using the test_configs method:

# Test configurations from a file
best_config = client.test_configs("configs.txt", output_file="valid_configs.txt", min_latency=50, max_latency=500)
if best_config:
    print(f"Best configuration: {best_config}")

# Test configurations from a list
configs = [
    "vless://user1@server1:443?security=tls&type=tcp#Server1",
    "vless://user2@server2:443?security=tls&type=tcp#Server2",
]
best_config = client.test_configs(configs, output_file="valid_configs.txt", min_latency=50, max_latency=500)
if best_config:
    print(f"Best configuration: {best_config}")

Resetting Network Proxy

To reset the system network proxy settings, use the reset_network_proxy method:

client.reset_network_proxy()
print("Network proxy settings reset successfully!")

Working with Subscriptions

V2ROOT 1.2.0 introduces subscription management for handling multiple V2Ray configurations:

Getting Configurations from Subscriptions

from v2root import SubscriptionManager, V2ROOT

# Create subscription manager
manager = SubscriptionManager()

# Add a subscription
sub = manager.add_subscription(
    url="https://example.com/subscription",
    name="My VPN Provider"
)

# Get all configuration strings
all_configs = manager.get_all_configs()
print(f"Total configs: {len(all_configs)}")

# Get configs from specific subscription
configs = manager.get_configs_from_subscription(sub.id)
print(f"Configs in this subscription: {len(configs)}")

Using Subscription Configurations

from v2root import V2ROOT, SubscriptionManager

v2 = V2ROOT()
manager = SubscriptionManager()

# Get all configs
all_configs = manager.get_all_configs()

# Test and use the first one
if all_configs:
    latency = v2.test_connection(all_configs[0])
    print(f"Latency: {latency}ms")

    v2.set_config_string(all_configs[0])
    v2.start()

    # ... use the connection ...

    v2.stop()

Finding the Best Configuration

from v2root import V2ROOT, SubscriptionManager

v2 = V2ROOT()
manager = SubscriptionManager()

# Get all configs
configs = manager.get_all_configs()

# Test all and find the fastest
best_config = None
best_latency = float('inf')

for config in configs:
    try:
        latency = v2.test_connection(config)
        if latency < best_latency:
            best_latency = latency
            best_config = config
    except:
        continue

# Use the best one
if best_config:
    print(f"Best config has {best_latency}ms latency")
    v2.set_config_string(best_config)
    v2.start()