v2ray-finder 0.2.1__tar.gz

v2ray_finder-0.2.1/CHANGELOG.md

@@ -0,0 +1,177 @@
+# Changelog
+
+All notable changes to v2ray-finder will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.2.1] - 2026-02-24
+
+### Fixed
+
+- **Graceful stop / Ctrl+C handling** — complete overhaul across all layers:
+
+  **`core.py` — `get_servers_from_known_sources()`**
+  - Added `try/except KeyboardInterrupt` around each URL fetch
+  - On interrupt: calls `self.request_stop()`, breaks the loop, returns
+    whatever was already collected (partial results are no longer lost)
+
+  **`core.py` — `get_servers_from_github()`**
+  - Same `try/except KeyboardInterrupt` pattern applied to the repo-file
+    iteration loop
+  - Partial results from files fetched before Ctrl+C are preserved
+
+  **`core.py` — `get_servers_with_health()`**
+  - Added `health_batch_size` parameter (default `50`) to split the
+    server list into smaller batches
+  - `should_stop()` is checked between every batch — no longer necessary
+    to wait for all health checks to finish before the stop takes effect
+  - `try/except KeyboardInterrupt` inside the batch loop: already-checked
+    servers are returned immediately on interrupt
+
+  **`cli.py` — interactive menu**
+  - Removed `start_keyboard_listener()` / `stop_keyboard_listener()` calls
+    from `interactive_menu()` — the background thread competed with the
+    menu's own `input()` calls, silently discarding the first keystroke
+    after each operation
+  - Every menu operation (options 1–5) now has its own
+    `try/except KeyboardInterrupt` with partial-results save
+  - Replaced bare boolean `_stop_listener` flag with `threading.Event`
+    inside `StopController` for thread-safe lifecycle control
+  - `StopController` (listener thread) is now used **only** in the
+    non-interactive (`--output` / `--stats-only`) path where the main
+    thread never calls `input()` during a fetch
+
+  **`cli_rich.py` — Rich interactive mode**
+  - `_signal_handler()` now calls `_active_finder.request_stop()` before
+    re-raising `KeyboardInterrupt`; previously it only set a bare boolean
+    that the core loops never checked
+  - `fetch_servers()` updates the `partial` snapshot after every
+    individual step (known sources, then GitHub search) so a Ctrl+C at
+    any point yields whatever was collected up to that moment
+  - `StopController` (same pattern as plain CLI) used only in
+    non-interactive path to avoid competing `input()` threads
+
+### Tests
+
+- Added `TestHealthBatchStop` class to `tests/test_stop_mechanism.py`:
+  - `test_ki_during_batch_returns_partial` — KI on batch N returns
+    results from batches 1…N-1 and sets `should_stop()`
+  - `test_ki_does_not_propagate` — `KeyboardInterrupt` must not escape
+    `get_servers_with_health()`
+  - `test_should_stop_between_batches_stops_processing` — once
+    `should_stop()` is `True`, no further `check_servers()` calls are made
+  - `test_custom_batch_size_splits_work` — `health_batch_size=2` with 6
+    servers results in exactly 3 `check_servers()` calls
+
+---
+
+## [0.2.0] - 2026-02-20
+
+### Added
+
+- **Async HTTP Fetching** (`async_fetcher` module)
+  - 10-50x faster concurrent downloads via `asyncio`
+  - Multiple backends: aiohttp (preferred), httpx, or sync fallback
+  - Connection pooling and per-request timeout control
+  - Automatic retry with exponential backoff (configurable `max_retries`)
+  - `fetch_urls_concurrently()` convenience function
+
+- **Smart Caching Layer** (`cache` module)
+  - Memory cache (fast, temporary) and disk cache (persistent via `diskcache`)
+  - Configurable TTL per entry
+  - Cache statistics: hit rate, hits, misses
+  - `@cache.cached('key', ttl=3600)` decorator support
+  - Automatic expiration and cleanup
+
+- **Enhanced Error Handling** (`exceptions` + `result` modules)
+  - `Result[T, E]` type for explicit error handling (`.is_ok()`, `.unwrap()`, `.error`)
+  - Custom exception hierarchy: `V2RayFinderError`, `RateLimitError`, `AuthenticationError`, `NetworkError`, `TimeoutError`, `ParseError`, `RepositoryNotFoundError`
+  - `raise_errors=True` constructor flag for exception-based error handling
+  - `search_repos_or_empty()` and `get_repo_files_or_empty()` compatibility wrappers
+
+- **Health Checking** (`health_checker` module)
+  - TCP connectivity verification with precise latency measurement
+  - Config format validation for vmess, vless, trojan, ss, ssr
+  - Concurrent batch health checks via asyncio semaphore
+  - Quality scoring (0–100) based on latency thresholds
+  - `filter_healthy_servers()` — filter by status and quality score
+  - `sort_by_quality()` — sort servers best-first
+
+- **Secure Token Handling**
+  - Automatic `GITHUB_TOKEN` environment variable reading on init
+  - Token format validation and sanitization (length, character set, known prefixes)
+  - `V2RayServerFinder.from_env()` factory classmethod
+  - Security warnings logged when token passed directly as parameter
+
+- **Rate Limit Tracking**
+  - `get_rate_limit_info()` — returns last known limit, remaining, and reset time
+  - Automatic warning logged when remaining requests drop below 10
+
+- **Test Suite** (78% coverage)
+  - Unit tests for all core modules
+  - Async tests using `pytest-asyncio`
+  - Health checker tests with full TCP mocking
+  - CI matrix: Python 3.8–3.12 on Linux, macOS, and Windows
+
+### Changed
+
+- `V2RayServerFinder.__init__` now accepts `raise_errors: bool = False`
+- `search_repos()` now returns `Result[List[Dict], V2RayFinderError]` instead of raw list
+- Rate limit checking moved after HTTP status checks to avoid mock-related issues
+
+### Technical Notes
+
+- No breaking changes for basic usage (`get_all_servers()`, `save_to_file()`)
+- GUI module excluded from coverage (requires display server)
+- All async code is Python 3.8-compatible (no `asyncio.run()` in public API)
+
+---
+
+## [0.1.0] - 2026-01-15
+
+### First Release
+
+#### Added
+
+**Core Functionality:**
+- GitHub repository search for public V2Ray configs
+- Curated direct subscription sources (3 reliable sources)
+- Protocol support: vmess, vless, trojan, shadowsocks (ss), ssr
+- Automatic deduplication of server configs
+
+**Interfaces:**
+- Python API (`V2RayServerFinder`)
+- CLI (simple interactive TUI via `v2ray-finder`)
+- Rich CLI with colored panels and progress bars (`v2ray-finder-rich`)
+- GUI (PySide6/Qt via `v2ray-finder-gui`)
+
+**Export:**
+- Save server list to `.txt` files
+- Protocol statistics display
+
+---
+
+## Project Statistics
+
+| Metric | Value |
+|--------|-------|
+| Source Lines | ~2,500+ |
+| Test Files | 8 |
+| Test Coverage | ~82% |
+| Supported Protocols | 5 (vmess, vless, trojan, ss, ssr) |
+| Interfaces | 3 (Python API, CLI, GUI) |
+| Python Versions | 3.8 – 3.12 |
+| Platforms | Linux, macOS, Windows |
+| Languages | 3 (\u0641\u0627\u0631\u0633\u06cc, English, Deutsch) |
+
+---
+
+## Contributors
+
+- Ali Sadeghi Aghili ([@alisadeghiaghili](https://github.com/alisadeghiaghili)) — Creator & Maintainer
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

v2ray_finder-0.2.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ali Sadeghi Aghili
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights 
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is 
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall 
+be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
+SOFTWARE.

v2ray_finder-0.2.1/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include requirements.txt
+recursive-include src/v2ray_finder/gui *.ui *.qrc
+recursive-include tests *.py
+global-exclude __pycache__
+global-exclude *.py[co]

v2ray_finder-0.2.1/PKG-INFO

@@ -0,0 +1,405 @@
+Metadata-Version: 2.4
+Name: v2ray-finder
+Version: 0.2.1
+Summary: Search and collect V2Ray servers from GitHub repositories
+Author-email: Ali Sadeghi Aghili <alisadeghiaghili@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/alisadeghiaghili/v2ray-finder
+Project-URL: Repository, https://github.com/alisadeghiaghili/v2ray-finder
+Project-URL: Issues, https://github.com/alisadeghiaghili/v2ray-finder/issues
+Project-URL: Source Code, https://github.com/alisadeghiaghili/v2ray-finder
+Keywords: v2ray,proxy,vpn,github,vmess,vless,trojan,shadowsocks,subscription
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: gui
+Requires-Dist: PySide6>=6.4.0; extra == "gui"
+Provides-Extra: cli-rich
+Requires-Dist: rich>=13.7.0; extra == "cli-rich"
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.8.0; extra == "async"
+Requires-Dist: httpx>=0.24.0; extra == "async"
+Provides-Extra: cache
+Requires-Dist: diskcache>=5.6.0; extra == "cache"
+Provides-Extra: all
+Requires-Dist: PySide6>=6.4.0; extra == "all"
+Requires-Dist: rich>=13.7.0; extra == "all"
+Requires-Dist: aiohttp>=3.8.0; extra == "all"
+Requires-Dist: httpx>=0.24.0; extra == "all"
+Requires-Dist: diskcache>=5.6.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: isort>=5.12; extra == "dev"
+Requires-Dist: aiohttp>=3.8.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Requires-Dist: diskcache>=5.6.0; extra == "dev"
+Dynamic: license-file
+
+# v2ray-finder
+
+[![PyPI version](https://badge.fury.io/py/v2ray-finder.svg)](https://badge.fury.io/py/v2ray-finder)
+[![Python Versions](https://img.shields.io/pypi/pyversions/v2ray-finder.svg)](https://pypi.org/project/v2ray-finder/)
+[![Tests](https://github.com/alisadeghiaghili/v2ray-finder/workflows/Tests/badge.svg)](https://github.com/alisadeghiaghili/v2ray-finder/actions)
+[![Code Quality](https://github.com/alisadeghiaghili/v2ray-finder/workflows/Code%20Quality/badge.svg)](https://github.com/alisadeghiaghili/v2ray-finder/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![GitHub Stars](https://img.shields.io/github/stars/alisadeghiaghili/v2ray-finder?style=flat)](https://github.com/alisadeghiaghili/v2ray-finder/stargazers)
+
+[English](README.en.md) | [فارسی](README.fa.md) | [Deutsch](README.de.md) | [📋 CHANGELOG](CHANGELOG.md)
+  
+
+---
+
+A **high-performance** tool to **fetch, aggregate, validate and health-check public V2Ray server configs** from GitHub and curated subscription sources.
+
+هدف این ابزار این است که بدون دردسر، یک لیست تمیز و dedup شده از لینک‌های `vmess://`، `vless://`، `trojan://`، `ss://`، `ssr://` بهت بده.
+
+**با عشق برای آزادی همیشگی ❤️**  
+**Built with love for eternal freedom ❤️**
+
+---
+
+## 🚀 What's New in v0.2.0
+
+### 🎉 Major Performance & Reliability Release!
+
+⚡ **Async HTTP Fetching** — 10-50x faster concurrent downloads  
+💾 **Smart Caching** — 80-95% fewer GitHub API calls  
+🛡️ **Enhanced Error Handling** — Result type + custom exception hierarchy  
+🔒 **Secure Token Handling** — Environment variable support + `from_env()`  
+🧪 **78% Test Coverage** — Comprehensive test suite across Python 3.8–3.12  
+📈 **Rate Limit Tracking** — Monitor GitHub API usage  
+🏥 **Health Checking** — TCP connectivity, latency measurement, quality scoring  
+⌨️ **Interactive Token Prompt** — Secure masked input with `--prompt-token`  
+⛔ **Graceful Interruption** — Press Ctrl+C to save partial results  
+
+> See full details in [📋 CHANGELOG.md](CHANGELOG.md)
+
+---
+
+## 🎯 Features / ویژگی‌ها
+
+### Core Features / ویژگی‌های اصلی
+- 🔍 **GitHub repository search** + **curated sources**
+- 🚀 **Three interfaces**: Python API, CLI (simple & rich), GUI (PySide6)
+- 📦 **Deduplicated** and **clean** output
+- 🌐 **Supports**: vmess, vless, trojan, shadowsocks, ssr
+- 💾 **Export** to text files
+- 📊 **Statistics** by protocol
+
+### Performance & Reliability / کارایی و قابلیت اطمینان
+- ⚡ **Async HTTP fetching**: **10-50x faster** concurrent downloads
+- 💾 **Smart caching**: **80-95% fewer** API calls with memory/disk cache
+- ✅ **Health checking**: TCP connectivity, latency measurement, config validation
+- 🎯 **Quality scoring**: Rank servers by speed and reliability
+- 🔄 **Retry logic**: Automatic retry with exponential backoff
+- ⛔ **Graceful interruption**: Ctrl+C saves partial results before exit
+
+### Developer Experience / تجربه توسعه‌دهنده
+- 🛡️ **Robust error handling**: Detailed exception hierarchy with proper error propagation
+- 📈 **Rate limit tracking**: Monitor GitHub API usage
+- 🔒 **Secure token handling**: Environment variable support with validation
+- ⌨️ **Interactive token prompt**: Masked input for secure token entry
+- 🧪 **78% test coverage**: Comprehensive test suite across Linux, macOS, and Windows
+- ✅ **CI/CD**: Automated testing and deployment
+
+---
+
+## 📋 Requirements / پیش‌نیازها
+
+- **Python** ≥ 3.8
+- **Internet connection**
+- **Optional**: aiohttp/httpx (async), diskcache (caching), PySide6 (GUI)
+
+---
+
+## 📦 Installation / نصب
+
+```bash
+# Core + lightweight CLI
+pip install v2ray-finder
+
+# With async support (10-50x faster!)
+pip install "v2ray-finder[async]"
+
+# With caching (80-95% fewer API calls!)
+pip install "v2ray-finder[cache]"
+
+# With GUI support (PySide6)
+pip install "v2ray-finder[gui]"
+
+# With Rich CLI
+pip install "v2ray-finder[cli-rich]"
+
+# Everything (recommended)
+pip install "v2ray-finder[all]"
+```
+
+### From source / از سورس
+
+```bash
+git clone https://github.com/alisadeghiaghili/v2ray-finder.git
+cd v2ray-finder
+pip install -e ".[all,dev]"
+```
+
+---
+
+## 🔒 Token Security / امنیت Token
+
+### Method 1: Environment Variable (Recommended)
+
+```bash
+# پیشنهادی / Recommended
+export GITHUB_TOKEN="ghp_your_token_here"
+v2ray-finder -s
+```
+
+```python
+from v2ray_finder import V2RayServerFinder
+
+finder = V2RayServerFinder()          # reads GITHUB_TOKEN automatically
+finder = V2RayServerFinder.from_env() # explicit
+```
+
+### Method 2: Interactive Prompt (New! ✨)
+
+```bash
+# Secure masked input
+v2ray-finder --prompt-token -s -o servers.txt
+v2ray-finder-rich --prompt-token
+
+# In interactive mode (no args), you'll be prompted automatically
+v2ray-finder-rich
+# → "Do you want to provide a GitHub token? (y/n)"
+```
+
+**Rate Limits:** without token: 60 req/h — with token: 5000 req/h
+
+Generate a token at **GitHub Settings → Developer settings → Personal access tokens** with **public_repo** scope.
+
+> ⚠️ **Security Note:** Never use `-t` flag for tokens (insecure). Use env var or `--prompt-token` instead.
+
+---
+
+## ⛔ Graceful Interruption (New! ✨)
+
+**Press Ctrl+C at any time** during fetch operations to:
+- Stop immediately without data loss
+- Save all servers collected so far
+- Display statistics for partial results
+- Exit cleanly with code `130`
+
+```bash
+v2ray-finder -s -o servers.txt
+# ... fetching ...
+# Press Ctrl+C
+
+[!] Interrupted by user. Saving partial results...
+[✓] Saved 47 servers to v2ray_servers_partial.txt
+
+Total servers: 47
+By protocol:
+  vmess: 23
+  vless: 15
+  trojan: 9
+```
+
+**Rich CLI** version:
+
+```bash
+v2ray-finder-rich -s
+# Press Ctrl+C during fetch
+
+⚠ Interrupted by user
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
+✓ Saved 47 servers to v2ray_servers_partial.txt
+```
+
+> 📖 **See detailed guide:** [docs/INTERRUPTION_GUIDE.md](docs/INTERRUPTION_GUIDE.md)
+
+---
+
+## 📚 Library Usage / استفاده به‌صورت کتابخانه
+
+```python
+from v2ray_finder import V2RayServerFinder
+
+finder = V2RayServerFinder()
+
+# Fast: curated sources only
+servers = finder.get_all_servers()
+print(f"Total: {len(servers)}")
+
+# Extended: curated + GitHub search
+servers = finder.get_all_servers(use_github_search=True)
+
+# Save to file
+count, filename = finder.save_to_file(filename="v2ray_servers.txt", limit=200)
+```
+
+### Error Handling
+
+```python
+from v2ray_finder import V2RayServerFinder, RateLimitError, NetworkError
+
+# Method 1: Result type
+result = finder.search_repos(keywords=["v2ray"])
+if result.is_ok():
+    repos = result.unwrap()
+else:
+    print(result.error)
+
+# Method 2: Exception mode
+finder = V2RayServerFinder(raise_errors=True)
+try:
+    repos = finder.search_repos_or_empty()
+except RateLimitError as e:
+    print(f"Rate limit: {e}")
+```
+
+### Health Checking
+
+```python
+servers = finder.get_servers_with_health(
+    check_health=True,
+    health_timeout=5.0,
+    min_quality_score=60.0,
+    filter_unhealthy=True,
+)
+for s in servers[:10]:
+    print(f"{s['protocol']:8s} | Quality: {s['quality_score']:5.1f} | {s['latency_ms']:6.1f}ms")
+```
+
+---
+
+## ⚡ CLI Usage / استفاده از CLI
+
+### Basic CLI
+
+```bash
+export GITHUB_TOKEN="ghp_your_token_here"
+
+v2ray-finder                          # Interactive TUI
+v2ray-finder -o servers.txt           # Quick save
+v2ray-finder -s -l 200 -o servers.txt # GitHub search + limit
+v2ray-finder --stats-only             # Stats only
+v2ray-finder --prompt-token -s        # Secure token input
+```
+
+**With health checking:**
+
+```bash
+v2ray-finder -c --min-quality 60 -o healthy_servers.txt
+```
+
+### Rich CLI (Recommended)
+
+```bash
+pip install "v2ray-finder[cli-rich]"
+v2ray-finder-rich                     # Beautiful Rich TUI
+v2ray-finder-rich --prompt-token      # With secure token prompt
+```
+
+**Interactive mode features:**
+- Token prompt on first run (if not in env)
+- Press Ctrl+C during fetch → saves partial results
+- Visual progress bars and spinners
+- Color-coded health status
+
+---
+
+## 🖥️ GUI / رابط گرافیکی
+
+```bash
+pip install "v2ray-finder[gui]"
+v2ray-finder-gui
+```
+
+---
+
+## 🛠️ Advanced Usage
+
+### Interruption in Scripts
+
+```bash
+#!/bin/bash
+
+v2ray-finder -s -o servers.txt
+exit_code=$?
+
+if [ $exit_code -eq 0 ]; then
+    echo "Success!"
+    # Process servers.txt
+elif [ $exit_code -eq 130 ]; then
+    echo "Interrupted - using partial results"
+    mv v2ray_servers_partial.txt servers.txt
+else
+    echo "Error occurred"
+    exit 1
+fi
+```
+
+### CI/CD with Timeout
+
+```bash
+# Timeout after 2 minutes, use partial results
+timeout 120 v2ray-finder -s -o servers.txt || {
+    if [ $? -eq 124 ]; then
+        mv v2ray_servers_partial.txt servers.txt
+    fi
+}
+```
+
+---
+
+## 🤝 Contributing / مشارکت
+
+```bash
+pytest tests/ -v
+black . && isort . && flake8 src/
+```
+
+---
+
+## 📝 License
+
+MIT License © 2026 Ali Sadeghi Aghili
+
+---
+
+## 🔗 Links
+
+- [Repository](https://github.com/alisadeghiaghili/v2ray-finder)
+- [PyPI](https://pypi.org/project/v2ray-finder)
+- [Issues](https://github.com/alisadeghiaghili/v2ray-finder/issues)
+- [CHANGELOG](CHANGELOG.md)
+- [Interruption Guide](docs/INTERRUPTION_GUIDE.md)
+
+---
+
+## 🙏 Acknowledgments / تشکرات
+
+- [ebrasha/free-v2ray-public-list](https://github.com/ebrasha/free-v2ray-public-list)
+- [barry-far/V2ray-Config](https://github.com/barry-far/V2ray-Config)
+- [Epodonios/v2ray-configs](https://github.com/Epodonios/v2ray-configs)
+
+و تمامی توسعه‌دهندگانی که کانفیگ‌های آزاد منتشر می‌کنند ❤️