ResourcePool.Docs/README.md

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

ResourcePool Usage Guide

This guide provides instructions on how to set up and use the TokenPool ProxyPool in your project.

---

Installation

1. Add the following NuGet package references to your project:

   Icomm.ResourcePool.Abstractions
   

   Icomm.TokenPool
   

   Icomm.ProxyPool
   

---

Service Registration

Register the necessary services in the Startup.cs or equivalent service configuration file:

services
    .AddConfigManager(hostContext.Configuration)
    .AddTokenPool(
        hostContext.Configuration,
        opt =>
        {
#if DEBUG
            opt.Host = "10.9.3.70";
            opt.protocol = ResourcePool.Core.Protocol.Grpc;
            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
        }
    )
    ;

---

Usage TokenPool

Once the services are registered, you can inject and use the ITokenPoolService in your application.

Example:

private readonly ITokenPoolService _tokenPoolService;

public MyService(ITokenPoolService tokenPoolService)
{
    _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}");
}

• The ITokenPoolService provides methods to interact with the Token Pool.
• Ensure that the service is properly registered and injected where needed.

---

Usage ProxyPool

Once the services are registered, you can inject and use the IProxyPoolService in your application.

Example:

private readonly IProxyPoolService _proxyPool;;

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}");
}

// example with EstimateRequest
public async Task UseRawProxyPoolWithRestSharp()
{
    // Example usage of the _tokenPoolService
    var proxy = await _proxyPool.GetRawProxyServerAsync(
                cancellationToken: cancellationToken
            );
    var clientOptions = new RestClientOptions(url)
    {
        Proxy = new WebProxy(proxy.Host, proxy.Port)
    };      
    Console.WriteLine($"Retrieved Token: {token}");
}

• The ITokenPoolService IProxyPoolService provides methods to interact with the Token Pool.
• Ensure that the service is properly registered and injected where needed.

---

Notes

• 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.

---

API Documentation

Proxy Pool API - GetProxyByFeature

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

Parameter	Type	Required	Description
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ố

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

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

1. 🎲 Random Strategy (strategy: "random")

• Tham số bắt buộc: type
• Tham số tùy chọn: country
• Mô tả: Chọn ngẫu nhiên proxy từ pool phù hợp
• Ví dụ:

{
  "type": "httpv6",
  "strategy": "random",
  "country": "VN"
}

2. ⚖️ Round Robin Strategy (strategy: "round_robin")

• Tham số bắt buộc: type
• Tham số tùy chọn: country
• Mô tả: Phân phối request đều khắp các proxy trong pool
• Ví dụ:

{
  "type": "http",
  "strategy": "round_robin",
  "country": "US"
}

3. 📊 Least Used Strategy (strategy: "least_used")

• Tham số bắt buộc: referer_proxy.id
• Mô tả: Chọn proxy có tần suất sử dụng thấp nhất
• Logic đặc biệt: Sử dụng thông tin referer_proxy làm tham số lọc chính
• Ví dụ:

{
  "strategy": "least_used",
  "referer_proxy": {
    "id": 123
  },
  "type": "httpv6",
  "country": "VN"
}

4. ⚡ Least Delay Strategy (strategy: "least_delay")

• Tham số bắt buộc: target_domain, type
• Tham số tùy chọn: country
• Mô tả: Chọn proxy có độ trễ thấp nhất cho domain cụ thể
• Ví dụ:

{
  "target_domain": "facebook.com",
  "type": "httpv6",
  "strategy": "least_delay",
  "country": "US"
}

5. 🏆 Adaptive Ranking Strategy (strategy: "adaptive_ranking")

• Tham số bắt buộc: target_domain, type
• Tham số tùy chọn: country
• Mô tả: Chọn proxy có điểm số cao nhất (tỷ lệ thành công + tốc độ response)
• Ví dụ:

{
  "target_domain": "instagram.com",
  "type": "http",
  "strategy": "adaptive_ranking",
  "country": "JP"
}

📤 Response Format

{
  "proxy": {
    "id": 123,
    "host": "192.168.1.100",
    "port": 8080,
    "type": "httpv6",
    "country": "VN",
    "location": "Ho Chi Minh City",
    "status": 1,
    "auth_username": "user",
    "auth_password": "password",
    "cluster": "cluster1",
    "source": "manual",
    "updateTime": "2024-01-15T10:30:00Z"
  }
}

🔧 Example Usage

Sử dụng với HttpClient:

var request = new ProxyRequestByFeature
{
    Type = "httpv6",
    Strategy = "adaptive_ranking",
    TargetDomain = "facebook.com",
    Country = "VN"
};

var response = await httpClient.PostAsJsonAsync(
    "/api/resource-pool/v1/ProxyPool/get-v2", 
    request
);

var proxyData = await response.Content.ReadFromJsonAsync<ProxyResponse>();

// 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}");

Sử dụng với RestSharp:

var request = new RestRequest("/api/resource-pool/v1/ProxyPool/get-v2", Method.Post);
request.AddJsonBody(new ProxyRequestByFeature
{
    Type = "http",
    Strategy = "least_delay",
    TargetDomain = "instagram.com",
    Country = "US"
});

var response = await client.ExecuteAsync<ProxyResponse>(request);
var proxy = new WebProxy($"{response.Data.Proxy.Host}:{response.Data.Proxy.Port}")
{
    Credentials = new NetworkCredential(response.Data.Proxy.AuthUsername, response.Data.Proxy.AuthPassword)
};

var restClient = new RestClient("https://api.example.com")
{
    Proxy = proxy
};

---

Proxy Pool Diagram

Token Pool Diagram