diff --git a/README.md b/README.md index 0f6dead..b4d452f 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,21 @@ -# Service quản trị Resource trong hệ thống, +# Service quản trị Resource trong hệ thống + - Hỗ trợ 2 giao thức: http(31249), grpc(31287) - Quản trị 2 resource: proxy pool, token pool +> **📖 Migration Guide**: Nếu bạn đang sử dụng ProxyPool và muốn migrate sang SmartPool, xem [Migration Guide](./MIGRATION_GUIDE_PROXYPOOL_TO_SMARTPOOL.md) + +--- + # ResourcePool Usage Guide -This guide provides instructions on how to set up and use the **TokenPool** **ProxyPool** in your project. +This guide provides instructions on how to set up and use **TokenPool** and **ProxyPool** in your project. + +> **Note**: This repository contains two systems: +> - **ResourcePool** (Legacy): TokenPool và ProxyPool với gRPC/HTTP API +> - **SmartPool** (New): Intelligent proxy management với SDK client +> +> Xem [SmartPool documentation](./src/Icomm.SmartPool.Proxy/README.md) cho hệ thống mới. --- @@ -12,21 +23,21 @@ This guide provides instructions on how to set up and use the **TokenPool** **P 1. Add the following NuGet package references to your project: ```xml - Icomm.ResourcePool.Abstractions - ``` - ```xml - Icomm.TokenPool - ``` - ```xml - Icomm.ProxyPool + + ``` + --- ## Service Registration -Register the necessary services in the `Startup.cs` or equivalent service configuration file: +### TokenPool Registration + +Register TokenPool service in `Startup.cs` or `Program.cs`: ```csharp +using Icomm.TokenPool.Extensions; + services .AddConfigManager(hostContext.Configuration) .AddTokenPool( @@ -39,157 +50,175 @@ services opt.Port = 31287; #endif } - ) - .AddProxyPool( - hostContext.Configuration, - opt => - { -#if DEBUG - opt.Host = "10.9.3.70"; - opt.protocol = ResourcePool.Core.Protocol.Grpc; - opt.Port = 31287; -#endif - } - ) - ; + ); ``` +**Configuration Options:** +- `Host`: Server host address +- `Port`: Server port (default: 31287 for gRPC, 31249 for HTTP) +- `protocol`: `Protocol.Grpc` or `Protocol.Http` +- `TimeOut`: Request timeout in milliseconds + --- ## Usage TokenPool -Once the services are registered, you can inject and use the `ITokenPoolService` in your application. +Once the service is registered, you can inject and use `ITokenPoolService` in your application. + +### Basic Usage -### Example: ```csharp -private readonly ITokenPoolService _tokenPoolService; +using Icomm.TokenPool.Contracts; +using Icomm.ResourcePool.Abstractions.Requests; +using Icomm.ResourcePool.Abstractions.Responses; -public MyService(ITokenPoolService tokenPoolService) +public class MyService { - _tokenPoolService = tokenPoolService; -} -// example with EstimateRequest -public async Task UseTokenPool() -{ - // Example usage of the _tokenPoolService - var token = await _tokenPoolService.RequestToken( - new TokenRequest() - { - EstimateRequest = 1, - Action = action, - Platform = "1", - } - ); - Console.WriteLine($"Retrieved Token: {token}"); -} -// example withouy EstimateRequest -public async Task UseTokenPool() -{ - // Example usage of the _tokenPoolService - var token = await _tokenPoolService.RequestToken( - new TokenRequest() - { - Action = action, - Platform = "1", - } - ); - await _tokenPoolService.UsedToken(token); - Console.WriteLine($"Retrieved Token: {token}"); + private readonly ITokenPoolService _tokenPoolService; + + public MyService(ITokenPoolService tokenPoolService) + { + _tokenPoolService = tokenPoolService; + } + + // Example with EstimateRequest + public async Task UseTokenPool() + { + var token = await _tokenPoolService.RequestToken( + new TokenRequest() + { + AccessToken = "your-access-token", + EstimateRequest = 1, + Action = "action-name", + Platform = "1", + } + ); + Console.WriteLine($"Retrieved Token: {token.Token}"); + } + + // Example without EstimateRequest (manual release) + public async Task UseTokenPoolManual() + { + var token = await _tokenPoolService.RequestToken( + new TokenRequest() + { + AccessToken = "your-access-token", + Action = "action-name", + Platform = "1", + } + ); + + // Use token... + + // Release token when done + await _tokenPoolService.UsedToken(token); + Console.WriteLine($"Token released: {token.Token}"); + } } ``` -- The `ITokenPoolService` provides methods to interact with the Token Pool. -- Ensure that the service is properly registered and injected where needed. +### Available Methods + +- `RequestToken(TokenRequest request)`: Request a token from the pool +- `UsedToken(TokenApp token)`: Release a token back to the pool +- `ExpireByToken(ExpireByTokenRequest request)`: Expire a token by token value +- `ExpireById(ExpireByTokenIdRequest request)`: Expire a token by ID +- `UpdateStatus(UpdateResourceStatusRequest request)`: Update token status +- `ResourceExpired(TokenApp resource, TimeSpan timeExpire, string accessToken)`: Mark token as expired for a duration --- ## Usage ProxyPool -Once the services are registered, you can inject and use the `IProxyPoolService` in your application. +ProxyPool is accessed via **gRPC** or **HTTP REST API** directly. There is no client SDK like TokenPool. + +### gRPC Usage -### Example: ```csharp -private readonly IProxyPoolService _proxyPool;; +using Icomm.ResourcePool.Abstractions; +using Icomm.ResourcePool.Abstractions.Requests; +using MagicOnion.Client; -public MyService(IProxyPoolService proxyPool) -{ - _proxyPool = proxyPool; -} -// example with EstimateRequest -public async Task UseProxyPoolWithRestSharp() -{ - // Example usage of the _tokenPoolService - var proxy = await _proxyPool.GetProxyServerAsync( - cancellationToken: cancellationToken - ); - var clientOptions = new RestClientOptions(url) - { - Proxy = proxy - }; - Console.WriteLine($"Retrieved Token: {token}"); -} +// Create gRPC channel +var channel = GrpcChannel.ForAddress("http://10.9.3.70:31287"); +var client = MagicOnionClient.Create(channel); -// example with EstimateRequest -public async Task UseRawProxyPoolWithRestSharp() +// Get proxy +var request = new ProxyRequest { - // Example usage of the _tokenPoolService - var proxy = await _proxyPool.GetRawProxyServerAsync( - cancellationToken: cancellationToken - ); - var clientOptions = new RestClientOptions(url) + AccessToken = "your-access-token" +}; +var response = await client.GetProxy(request); +var proxy = response.Proxy; + +// Use proxy with HttpClient +var handler = new HttpClientHandler +{ + Proxy = new WebProxy($"{proxy.Host}:{proxy.Port}") { - Proxy = new WebProxy(proxy.Host, proxy.Port) - }; - Console.WriteLine($"Retrieved Token: {token}"); -} + Credentials = new NetworkCredential(proxy.AuthUsername, proxy.AuthPassword) + } +}; +var httpClient = new HttpClient(handler); ``` -- The `ITokenPoolService` `IProxyPoolService` provides methods to interact with the Token Pool. -- Ensure that the service is properly registered and injected where needed. +### HTTP REST API Usage ---- +#### Get Proxy (Simple) -## Notes +**Endpoint**: `POST /api/resource-pool/v1/ProxyPool/get` -- The `opt.Host`, `opt.Protocol`, and `opt.Port` configuration should match your environment settings. -- In production, replace the debug configurations with the appropriate production values. +```csharp +using RestSharp; ---- +var client = new RestClient("http://10.9.3.70:31249"); +var request = new RestRequest("/api/resource-pool/v1/ProxyPool/get", Method.Post); +request.AddJsonBody(new ProxyRequest +{ + AccessToken = "your-access-token" +}); -## API Documentation +var response = await client.ExecuteAsync(request); +var proxy = response.Data.Proxy; -### Proxy Pool API - GetProxyByFeature +// Use with RestSharp +var restClient = new RestClient("https://target-site.com") +{ + Proxy = new WebProxy($"{proxy.Host}:{proxy.Port}") + { + Credentials = new NetworkCredential(proxy.AuthUsername, proxy.AuthPassword) + } +}; +``` -Endpoint: `POST /api/resource-pool/v1/ProxyPool/get-v2` +#### Get Proxy By Feature (Advanced) + +**Endpoint**: `POST /api/resource-pool/v1/ProxyPool/get-v2` Lấy proxy server theo features và chiến lược lọc cụ thể. -#### 📋 Request Parameters +**Request Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| +| `access_token` | string | **Required** | Access token for authentication | | `target_domain` | string | Optional | Domain đích cần truy cập (vd: facebook.com, x.com) | | `type` | string | **Required** | Loại proxy ("http", "httpv6", "socks") | | `country` | string | Optional | Mã quốc gia proxy ("VN", "US", "JP") | | `strategy` | string | **Required** | Chiến lược chọn proxy | | `referer_proxy` | object | Optional | Proxy tham chiếu để tìm proxy thay thế tốt nhất | -#### ⚠️ Logic Ưu Tiên Tham Số +**⚠️ Logic Ưu Tiên Tham Số** -**Nếu `referer_proxy.id` khác null**: Hệ thống sẽ ưu tiên lấy thông tin từ proxy referer làm tham số lọc chính, sau đó mới sử dụng các tham số `type`, `country`, `target_domain` để lọc bổ sung. +Nếu `referer_proxy.id` khác null: Hệ thống sẽ ưu tiên lấy thông tin từ proxy referer làm tham số lọc chính, sau đó mới sử dụng các tham số `type`, `country`, `target_domain` để lọc bổ sung. -**Cách hoạt động**: -1. **Bước 1**: Hệ thống lấy thông tin của proxy có ID = `referer_proxy.id` -2. **Bước 2**: Sử dụng thông tin proxy đó (type, country, location) làm tiêu chí lọc chính -3. **Bước 3**: Áp dụng các tham số `type`, `country`, `target_domain` như điều kiện lọc bổ sung -4. **Bước 4**: Thực hiện strategy được chọn trên pool đã được lọc +**Cách hoạt động:** +1. Hệ thống lấy thông tin của proxy có ID = `referer_proxy.id` +2. Sử dụng thông tin proxy đó (type, country, location) làm tiêu chí lọc chính +3. Áp dụng các tham số `type`, `country`, `target_domain` như điều kiện lọc bổ sung +4. Thực hiện strategy được chọn trên pool đã được lọc -**Lợi ích**: -- Tìm proxy thay thế có đặc tính tương tự với proxy đang sử dụng -- Đảm bảo tính nhất quán trong quality và performance -- Hỗ trợ thuật toán fallback khi proxy hiện tại gặp vấn đề - -#### 🎯 Available Strategies +**🎯 Available Strategies** ##### 1. 🎲 Random Strategy (`strategy: "random"`) - **Tham số bắt buộc**: `type` @@ -198,6 +227,7 @@ Lấy proxy server theo features và chiến lược lọc cụ thể. - **Ví dụ**: ```json { + "access_token": "your-token", "type": "httpv6", "strategy": "random", "country": "VN" @@ -211,6 +241,7 @@ Lấy proxy server theo features và chiến lược lọc cụ thể. - **Ví dụ**: ```json { + "access_token": "your-token", "type": "http", "strategy": "round_robin", "country": "US" @@ -224,6 +255,7 @@ Lấy proxy server theo features và chiến lược lọc cụ thể. - **Ví dụ**: ```json { + "access_token": "your-token", "strategy": "least_used", "referer_proxy": { "id": 123 @@ -240,6 +272,7 @@ Lấy proxy server theo features và chiến lược lọc cụ thể. - **Ví dụ**: ```json { + "access_token": "your-token", "target_domain": "facebook.com", "type": "httpv6", "strategy": "least_delay", @@ -254,6 +287,7 @@ Lấy proxy server theo features và chiến lược lọc cụ thể. - **Ví dụ**: ```json { + "access_token": "your-token", "target_domain": "instagram.com", "type": "http", "strategy": "adaptive_ranking", @@ -261,7 +295,7 @@ Lấy proxy server theo features và chiến lược lọc cụ thể. } ``` -#### 📤 Response Format +**📤 Response Format** ```json { @@ -282,36 +316,55 @@ Lấy proxy server theo features và chiến lược lọc cụ thể. } ``` -#### 🔧 Example Usage +**🔧 Example Usage** **Sử dụng với HttpClient:** ```csharp +using System.Net; +using System.Net.Http; +using System.Net.Http.Json; + var request = new ProxyRequestByFeature { + AccessToken = "your-token", Type = "httpv6", Strategy = "adaptive_ranking", TargetDomain = "facebook.com", Country = "VN" }; +var httpClient = new HttpClient(); var response = await httpClient.PostAsJsonAsync( - "/api/resource-pool/v1/ProxyPool/get-v2", + "http://10.9.3.70:31249/api/resource-pool/v1/ProxyPool/get-v2", request ); var proxyData = await response.Content.ReadFromJsonAsync(); // Sử dụng proxy với HttpClient -var httpClient = new HttpClient(); -httpClient.DefaultRequestHeaders.Add("Proxy", - $"http://{proxyData.Proxy.AuthUsername}:{proxyData.Proxy.AuthPassword}@{proxyData.Proxy.Host}:{proxyData.Proxy.Port}"); +var handler = new HttpClientHandler +{ + Proxy = new WebProxy($"{proxyData.Proxy.Host}:{proxyData.Proxy.Port}") + { + Credentials = new NetworkCredential( + proxyData.Proxy.AuthUsername, + proxyData.Proxy.AuthPassword + ) + } +}; +var proxiedClient = new HttpClient(handler); ``` **Sử dụng với RestSharp:** ```csharp +using RestSharp; +using System.Net; + +var client = new RestClient("http://10.9.3.70:31249"); var request = new RestRequest("/api/resource-pool/v1/ProxyPool/get-v2", Method.Post); request.AddJsonBody(new ProxyRequestByFeature { + AccessToken = "your-token", Type = "http", Strategy = "least_delay", TargetDomain = "instagram.com", @@ -319,21 +372,59 @@ request.AddJsonBody(new ProxyRequestByFeature }); var response = await client.ExecuteAsync(request); -var proxy = new WebProxy($"{response.Data.Proxy.Host}:{response.Data.Proxy.Port}") +var proxy = response.Data.Proxy; + +var proxyObj = new WebProxy($"{proxy.Host}:{proxy.Port}") { - Credentials = new NetworkCredential(response.Data.Proxy.AuthUsername, response.Data.Proxy.AuthPassword) + Credentials = new NetworkCredential(proxy.AuthUsername, proxy.AuthPassword) }; var restClient = new RestClient("https://api.example.com") { - Proxy = proxy + Proxy = proxyObj }; ``` +**Log Proxy Usage:** + +**Endpoint**: `POST /api/resource-pool/v1/ProxyPool/used` + +```csharp +var logRequest = new ProxyLogRequest +{ + AccessToken = "your-token", + ProxyId = proxy.Id, + StatusCode = 200, + ResponseTimeMs = 450 +}; + +var logResponse = await client.PostAsJsonAsync( + "http://10.9.3.70:31249/api/resource-pool/v1/ProxyPool/used", + logRequest +); +``` + --- +## Notes -## Proxy Pool Diagram -![Proxy Pool Diagram](Diagram-Proxy.png) -## Token Pool Diagram -![Token Pool Diagram](Diagram-Token.png) \ No newline at end of file +- The `opt.Host`, `opt.Protocol`, and `opt.Port` configuration should match your environment settings. +- In production, replace the debug configurations with the appropriate production values. +- TokenPool supports both gRPC and HTTP protocols via `AddTokenPool` extension. +- ProxyPool is accessed directly via gRPC (`IProxyService`) or HTTP REST API endpoints. +- For SOCKS5 proxy support, see [HttpToSocks5Proxy](./src/HttpToSocks5Proxy/README.md). + +--- + +## SmartPool (New System) + +For the new intelligent proxy management system with SDK client, see: +- **[SmartPool SDK Documentation](./src/Icomm.SmartPool.Proxy/README.md)** +- **[SmartPool API Documentation](./src/Icomm.API.SmartPool/README.md)** + +--- + +## Diagrams + +- **Proxy Pool Diagram**: ![Proxy Pool Diagram](Diagram-Proxy.png) +- **Token Pool Diagram**: ![Token Pool Diagram](Diagram-Token.png) diff --git a/docs/src/HttpToSocks5Proxy/README.md b/docs/src/HttpToSocks5Proxy/README.md index dd49199..0298d52 100644 --- a/docs/src/HttpToSocks5Proxy/README.md +++ b/docs/src/HttpToSocks5Proxy/README.md @@ -1,10 +1,10 @@ -# HttpToSocks5Proxy - .NET 8.0 +# HttpToSocks5Proxy - .NET 10.0 -HTTP(S) to SOCKS5 proxy adapter for .NET 8.0 +HTTP(S) to SOCKS5 proxy adapter for .NET 10.0 ## Overview -This library implements `IWebProxy` interface to act as an HTTP(S) proxy while connecting to a SOCKS5 server behind the scenes. It has been upgraded from .NET Standard 2.0 to .NET 8.0 for better performance and modern features. +This library implements `IWebProxy` interface to act as an HTTP(S) proxy while connecting to a SOCKS5 server behind the scenes. It has been upgraded from .NET Standard 2.0 to .NET 10.0 for better performance and modern features. ## Features @@ -12,7 +12,7 @@ This library implements `IWebProxy` interface to act as an HTTP(S) proxy while c - ✅ Transparent HTTP to SOCKS5 conversion - ✅ Support for authentication - ✅ Custom DNS resolver support -- ✅ .NET 8.0 optimizations +- ✅ .NET 10.0 optimizations - ✅ Nullable reference types enabled ## Usage @@ -73,14 +73,14 @@ var httpClient = new HttpClient(handler); ### Changes from Previous Version -- **Target Framework**: Changed from `netstandard2.0;net45` to `net8.0` -- **Version**: Bumped to `2.0.0` +- **Target Framework**: Changed from `netstandard2.0;net45` to `net10.0` +- **Version**: Bumped to `10.0.0` - **Language Features**: Enabled nullable reference types -- **Performance**: Benefits from .NET 8.0 runtime improvements +- **Performance**: Benefits from .NET 10.0 runtime improvements ### Breaking Changes -- Minimum requirement is now .NET 8.0 +- Minimum requirement is now .NET 10.0 - No longer supports .NET Framework 4.5 or .NET Standard 2.0 ## Integration with SmartPool @@ -108,7 +108,7 @@ Target Website ### Dependencies -- .NET 8.0 Runtime +- .NET 10.0 Runtime - No external NuGet packages required ## License @@ -117,11 +117,15 @@ MIT License ## Version History -- **2.0.0** (2026-01-22) - - Upgraded to .NET 8.0 +- **10.0.0** (2026-01-22) + - Upgraded to .NET 10.0 - Enabled nullable reference types - Added modern C# language features +- **2.0.0** (Previous) + - .NET 8.0 + - Nullable reference types support + - **1.4.0** (Previous) - .NET Standard 2.0 / .NET Framework 4.5 - Original implementation diff --git a/docs/src/Icomm.API.SmartPool/README.md b/docs/src/Icomm.API.SmartPool/README.md index 23a03a3..5798c94 100644 --- a/docs/src/Icomm.API.SmartPool/README.md +++ b/docs/src/Icomm.API.SmartPool/README.md @@ -109,31 +109,110 @@ The API will be available at: **POST** `/api/smart-pool/v1/SmartProxy/get-proxy` +Get a proxy server based on strategy and filters. + +**Request Body:** ```json { "access_token": "your-token", "strategy": "least_delay", "target_domain": "facebook.com", - "ipVersion": "v6", + "ip_version": "v6", "protocol": "http", "country": "US" } ``` +**Response:** +```json +{ + "success": true, + "error_code": 0, + "message": null, + "proxy": { + "id": 123, + "host": "192.168.1.100", + "port": 8080, + "protocol": "http", + "ip_version": "v6", + "country": "US", + "auth_username": "user", + "auth_password": "pass" + } +} +``` + +**Available Strategies:** +- `round_robin` (default): Balanced distribution +- `random`: Random selection +- `least_delay`: Fastest proxy (requires `target_domain`) +- `adaptive_ranking`: Highest success rate (requires `target_domain`) +- `alternative`: Similar proxy replacement (requires `referer_proxy.id`) + ### Log Usage **POST** `/api/smart-pool/v1/SmartProxy/log-usage` +Log proxy usage for analytics and strategy optimization. + +**Request Body:** ```json { "access_token": "your-token", "proxy_id": 123, "target_domain": "facebook.com", "status_code": 200, - "response_time_ms": 450 + "response_time_ms": 450, + "error_message": null, + "request_id": "req-12345-abc" } ``` +### Get Available Strategies + +**GET** `/api/smart-pool/v1/SmartProxy/strategies` + +Get list of available proxy selection strategies. + +**Response:** +```json +{ + "strategies": [ + "round_robin", + "random", + "least_delay", + "adaptive_ranking", + "alternative" + ] +} +``` + +### Health Check + +**GET** `/api/smart-pool/v1/SmartProxy/health` + +Check API health status. + +**Response:** +```json +{ + "status": "healthy", + "timestamp": "2024-01-15T10:30:00Z" +} +``` + +### Upsert Proxy + +**POST** `/api/smart-pool/v1/SmartProxy/proxy/upsert` + +Add or update proxy metadata. + +### Add Access Mapping + +**POST** `/api/smart-pool/v1/SmartProxy/access-mapping/add` + +Add access token to cluster mapping. + ## gRPC Usage ```csharp diff --git a/docs/src/Icomm.SmartPool.Proxy/README.md b/docs/src/Icomm.SmartPool.Proxy/README.md index a539b27..82d5e54 100644 --- a/docs/src/Icomm.SmartPool.Proxy/README.md +++ b/docs/src/Icomm.SmartPool.Proxy/README.md @@ -94,11 +94,15 @@ public class MyService public async Task MakeRequestAsync() { // Get proxy as IWebProxy (ready for HttpClient) - var proxy = await _smartPoolClient.GetProxyAsync( - strategy: "least_delay", - targetDomain: "facebook.com", - ipVersion: "v6" - ); + var request = new GetProxyRequest + { + access_token = "your-token", + strategy = "least_delay", + target_domain = "facebook.com", + ip_version = "v6" + }; + + var proxy = await _smartPoolClient.GetProxyAsync(request); if (proxy != null) { @@ -108,13 +112,15 @@ public class MyService var response = await httpClient.GetAsync("https://facebook.com"); // Log usage - await _smartPoolClient.LogProxyUsageAsync( - accessToken: "your-token", - proxyId: 123, - targetDomain: "facebook.com", - statusCode: (int)response.StatusCode, - responseTimeMs: 450 - ); + var logRequest = new ProxyUsageLogRequest + { + access_token = "your-token", + proxy_id = 123, // Get from GetRawProxyAsync if needed + target_domain = "facebook.com", + status_code = (int)response.StatusCode, + response_time_ms = 450 + }; + await _smartPoolClient.LogProxyUsageAsync(logRequest); } } } @@ -160,10 +166,10 @@ var alternativeProxy = await _smartPoolClient.GetRawProxyAsync(request); ## Strategies - **random**: Random selection -- **round_robin**: Balanced distribution -- **least_delay**: Fastest proxy (requires targetDomain) -- **adaptive_ranking**: Highest success rate (requires targetDomain) -- **alternative**: Similar proxy replacement (requires refererProxy) +- **round_robin**: Balanced distribution (default) +- **least_delay**: Fastest proxy (requires `target_domain`) +- **adaptive_ranking**: Highest success rate (requires `target_domain`) +- **alternative**: Similar proxy replacement (requires `referer_proxy.id`) ## Protocol Selection