Add files via upload

arshiacomplus · web-flow · commit 79cbaa6f8cfe · 2025-09-17T19:13:08.000+03:30
diff --git a/docs/python-v2ray/core-concepts/deduplicating-configs.md b/docs/python-v2ray/core-concepts/deduplicating-configs.md
@@ -0,0 +1,89 @@
+# Deduplicating Configurations
+
+When working with large lists of configurations, especially from multiple subscription links, it's common to encounter duplicates. These are profiles that are functionally identical (same server, port, and user ID) but may have different tags or remarks. Running tests on these duplicates is inefficient and clutters your results.
+
+The library provides a simple yet powerful utility function, `deduplicate_configs`, to clean up your list.
+
+## The Deduplication Strategy
+
+The function intelligently identifies duplicates by focusing on the **core properties** of a configuration, while **intentionally ignoring the `tag`**.
+
+-   **Unique Key**: For each configuration, a unique key is generated based on properties like `protocol`, `address`, `port`, and `id`/`password`.
+-   **First-Come, First-Served**: The function keeps the *first* occurrence of each unique configuration it encounters and discards all subsequent duplicates.
+
+This ensures that your final list is clean and ready for efficient testing.
+
+## Practical Example
+
+This minimal example demonstrates how to use `deduplicate_configs` to clean a list of `ConfigParams` objects.
+
+```python
+# examples/09_deduplicate_configs.py
+
+import os
+import sys
+
+# Add project root to path to find our library
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from python_v2ray.config_parser import load_configs, deduplicate_configs
+
+def main():
+    """
+    * A minimal example to demonstrate how to remove duplicate configurations
+    * from a list, ignoring their tags (# remarks).
+    """
+
+    # --- 1. Define a list with duplicate configurations ---
+    # Note: The first two VLESS configs are identical except for their tag.
+    raw_uris = [
+        "vless://abcdef@example.com:443?type=ws#VLESS-Config-1",
+        "vless://abcdef@example.com:443?type=ws#VLESS-Config-2-DUPLICATE",
+        "trojan://password@anotherexample.com:443#Trojan-Config-UNIQUE",
+    ]
+
+    print("--- Initial List of Raw URIs ---")
+    for uri in raw_uris:
+        print(f"- {uri}")
+
+    # --- 2. Load the configs into ConfigParams objects ---
+    parsed_configs = load_configs(source=raw_uris)
+    print(f"\n* Initially parsed {len(parsed_configs)} configurations.")
+
+    # --- 3. Apply the deduplication function ---
+    print("\n--- Applying Deduplication (Ignoring Tags) ---")
+    unique_configs = deduplicate_configs(parsed_configs)
+    
+    # --- 4. Display the final, clean list ---
+    print(f"\n* Found {len(unique_configs)} unique configurations.")
+    print("Tags of final unique configs:", [p.tag for p in unique_configs])
+
+if __name__ == "__main__":
+    main()
+```
+
+### Expected Output:
+```
+--- Initial List of Raw URIs ---
+- vless://abcdef@example.com:443?type=ws#VLESS-Config-1
+- vless://abcdef@example.com:443?type=ws#VLESS-Config-2-DUPLICATE
+- trojan://password@anotherexample.com:443#Trojan-Config-UNIQUE
+
+* Initially parsed 3 valid configurations.
+
+--- Applying Deduplication (Ignoring Tags) ---
+
+* Found 2 unique configurations.
+Tags of final unique configs: ['VLESS-Config-1', 'Trojan-Config-UNIQUE']
+```
+
+## API Reference
+
+### `deduplicate_configs()`
+
+```python
+def deduplicate_configs(configs: List[ConfigParams]) -> List[ConfigParams]:
+```
+
+-   **`configs`**: A list of `ConfigParams` objects to be cleaned.
+-   **Returns**: A new list containing only the unique `ConfigParams` objects.
diff --git a/docs/python-v2ray/core-concepts/loading-from-sources.md b/docs/python-v2ray/core-concepts/loading-from-sources.md
@@ -0,0 +1,100 @@
+# Loading Configs from Different Sources
+
+Manually managing individual configuration links can be tedious. The library provides a powerful and flexible universal loader, `load_configs`, to import profiles from various sources, including remote subscription links, local files, and Python lists.
+
+This function acts as the primary entry point for getting configurations into the system before testing or processing.
+
+## Key Features
+
+-   **Subscription Link Support**: Directly fetches and decodes configurations from remote subscription URLs.
+-   **Intelligent Decoding**: Automatically handles both **Base64-encoded** and **plain-text** subscription content.
+-   **Multiple Sources**: Accepts a URL, a local file path, or a Python list of URIs as input.
+-   **Robust Parsing**: Each raw URI is then processed by the internal `parse_uri` function to create a standardized `ConfigParams` object.
+
+## Using the `load_configs` Function
+
+The behavior of the function is controlled by two parameters: `source` and `is_subscription`.
+
+### Scenario 1: Loading from a Subscription URL
+
+This is the most common use case. Provide the URL and set the `is_subscription` flag to `True`.
+
+```python
+from python_v2ray.config_parser import load_configs
+
+sub_url = "https://your.subscription.link/path"
+
+# The flag tells the function to fetch the URL and decode its content
+parsed_configs = load_configs(source=sub_url, is_subscription=True)
+
+print(f"Loaded {len(parsed_configs)} configs from the subscription.")
+```
+
+### Scenario 2: Loading from a Local File
+
+You can load configurations from a local text file. The loader handles two types of files automatically.
+
+#### a) File with one URI per line
+
+```python
+# --- contents of my_configs.txt ---
+# vless://...
+# trojan://...
+
+from pathlib import Path
+from python_v2ray.config_parser import load_configs
+
+file_path = Path("my_configs.txt")
+
+# No flag is needed; this is the default behavior for files
+parsed_configs = load_configs(source=file_path)
+```
+
+#### b) File containing a single subscription link
+
+```python
+# --- contents of my_sub.txt ---
+# https://another.subscription.link/path
+
+from pathlib import Path
+from python_v2ray.config_parser import load_configs
+
+file_path = Path("my_sub.txt")
+
+# The flag tells the function to read the URL from the file and then fetch it
+parsed_configs = load_configs(source=file_path, is_subscription=True)
+```
+
+### Scenario 3: Loading from a Python List
+
+If you already have your configuration URIs in a Python list, you can pass it directly.
+
+```python
+from python_v2ray.config_parser import load_configs
+
+my_uri_list = [
+    "vless://abcdef@example.com:443?type=ws#Config-1",
+    "trojan://password@anotherexample.com:443#Config-2",
+]
+
+# This is the most direct way to parse a list of configs
+parsed_configs = load_configs(source=my_uri_list)
+```
+
+## API Reference
+
+### `load_configs()`
+
+```python
+def load_configs(
+    source: Union[str, List[str], Path], 
+    is_subscription: bool = False
+) -> List[ConfigParams]:
+```
+
+-   **`source`**: The input source. Can be:
+    -   A `str` representing a URL or a single URI.
+    -   A `list` of URI strings.
+    -   A `pathlib.Path` object pointing to a local file.
+-   **`is_subscription`** (optional): A boolean flag. Set to `True` if the `source` (or the content of the source file) is a subscription link that needs to be fetched and decoded. Defaults to `False`.
+-   **Returns**: A list of `ConfigParams` objects. **This function always returns a list**, even if it's empty.
diff --git a/docs/python-v2ray/core-concepts/proxy-chaining.md b/docs/python-v2ray/core-concepts/proxy-chaining.md
@@ -0,0 +1,109 @@
+# Proxy Chaining ("WARP on Any")
+
+This is one of the most powerful features of the library, allowing you to route the traffic of any Xray-compatible configuration through a final exit-point proxy. This is commonly used to enhance privacy or bypass complex network restrictions by creating a "WARP on Any" setup, where all your traffic exits through a Cloudflare WARP (WireGuard) endpoint.
+
+The implementation is seamless: once you provide a WARP configuration, the `XrayConfigBuilder` automatically configures all other outbounds to use it as their `dialerProxy`.
+
+## How It Works
+
+Instead of connecting directly to the internet, a primary outbound (like VLESS or Trojan) first routes its traffic through the specified WARP outbound. The traffic flow looks like this:
+
+`Your App` -> `Local SOCKS Inbound` -> `Primary Outbound (e.g., VLESS)` -> `WARP Outbound (WireGuard)` -> `Internet`
+
+This entire chain is managed within a single, merged Xray instance for maximum efficiency.
+
+## Practical Example: Testing Connectivity through WARP
+
+This example demonstrates how to test the connectivity (ping) of several configurations that are all forced to route their traffic through a single WARP profile.
+
+```python
+# examples/07_warp_tester.py
+
+import os
+import sys
+from pathlib import Path
+
+# Add project root to path
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from python_v2ray.downloader import BinaryDownloader
+from python_v2ray.tester import ConnectionTester
+from python_v2ray.config_parser import parse_uri
+
+def main():
+    project_root = Path(__file__).parent.parent
+    
+    # Ensure all necessary binaries are ready
+    downloader = BinaryDownloader(project_root)
+    downloader.ensure_all()
+
+    # --- 1. Define your WARP config (must be a WireGuard URI) ---
+    warp_uri = "wireguard://YOUR_PRIVATE_KEY@engage.cloudflareclient.com:2408?address=172.16.0.2/32&publicKey=...#WARP-Profile"
+
+    # --- 2. Define the primary configs to test THROUGH WARP ---
+    test_uris = [
+        "vless://YOUR_UUID@your.domain.com:443?type=ws#VLESS-through-WARP",
+        "trojan://YOUR_PASSWORD@another.domain.com:443#Trojan-through-WARP",
+        # You can even chain another WireGuard config through the main WARP config
+        # "wireguard://ANOTHER_PRIVATE_KEY@...#WG-on-WARP" 
+    ]
+    
+    # --- 3. Parse all configurations ---
+    parsed_warp_config = parse_uri(warp_uri)
+    parsed_test_configs = [p for p in (parse_uri(uri) for uri in test_uris) if p]
+
+    # --- Input Validation ---
+    if not parsed_warp_config or "YOUR_PRIVATE_KEY" in warp_uri:
+        print("! Please provide a valid WARP WireGuard URI.")
+        return
+    if not parsed_test_configs:
+        print("! No valid primary configurations found to test.")
+        return
+
+    tester = ConnectionTester(
+        vendor_path=str(project_root / "vendor"), 
+        core_engine_path=str(project_root / "core_engine")
+    )
+
+    # --- 4. Run the test, passing the WARP config to the `warp_config` parameter ---
+    print(f"\n--- Running Connectivity Test with WARP-on-Any enabled ---")
+    results = tester.test_uris(
+        parsed_params=parsed_test_configs,
+        warp_config=parsed_warp_config,
+        timeout=30  # Allow a longer timeout for chained connections
+    )
+
+    # --- 5. Print the results ---
+    if results:
+        print("\n" + "="*20 + " WARP ON ANY PING TEST RESULTS " + "="*20)
+        sorted_results = sorted(results, key=lambda x: x.get('ping_ms', 9999))
+        for result in sorted_results:
+            tag = result.get('tag', 'N/A')
+            ping = result.get('ping_ms', -1)
+            status = result.get('status', 'error')
+            
+            if status == 'success':
+                print(f"* Tag: {tag:<30} | Ping: {ping:>4} ms | Status: SUCCESS")
+            else:
+                print(f"! Tag: {tag:<30} | Ping: ---- ms | Status: FAILED ({status})")
+    else:
+        print("! No results were received from the tester.")
+
+if __name__ == "__main__":
+    main()
+```
+
+## API Reference: The `warp_config` Parameter
+
+To enable proxy chaining, a new optional parameter has been added to all primary testing methods:
+
+-   `test_uris(..., warp_config: Optional[ConfigParams] = None)`
+-   `test_speed(..., warp_config: Optional[ConfigParams] = None)`
+-   `test_upload(..., warp_config: Optional[ConfigParams] = None)`
+
+Simply pass a parsed `ConfigParams` object of a valid WireGuard configuration to this parameter, and the `ConnectionTester` will handle the rest.
+
+## Important Considerations
+
+-   The `warp_config` **must** be a valid `ConfigParams` object generated from a WireGuard URI.
+-   This chaining feature is handled by Xray's `dialerProxy`. Therefore, it only applies to protocols that are managed within the merged Xray instance (VLESS, VMess, Trojan, etc.). It does **not** apply to protocols like Hysteria that are launched in a separate, independent process by the Go test engine.
