# 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 **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](./docs/src/Icomm.SmartPool.Proxy/README.md) cho hệ thống mới.

---

## Installation

1. Add the following NuGet package references to your project:
   ```xml
   <PackageReference Include="Icomm.ResourcePool.Abstractions" Version="x.x.x" />
   <PackageReference Include="Icomm.TokenPool" Version="x.x.x" />
   ```

---

## Service Registration

### TokenPool Registration

Register TokenPool service in `Startup.cs` or `Program.cs`:

```csharp
using Icomm.TokenPool.Extensions;

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

**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 service is registered, you can inject and use `ITokenPoolService` in your application.

### Basic Usage

```csharp
using Icomm.TokenPool.Contracts;
using Icomm.ResourcePool.Abstractions.Requests;
using Icomm.ResourcePool.Abstractions.Responses;

public class MyService
{
    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}");
    }
}
```

### 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

ProxyPool is accessed via **gRPC** or **HTTP REST API** directly. There is no client SDK like TokenPool.

### gRPC Usage

```csharp
using Icomm.ResourcePool.Abstractions;
using Icomm.ResourcePool.Abstractions.Requests;
using MagicOnion.Client;

// Create gRPC channel
var channel = GrpcChannel.ForAddress("http://10.9.3.70:31287");
var client = MagicOnionClient.Create<IProxyService>(channel);

// Get proxy
var request = new ProxyRequest
{
    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}")
    {
        Credentials = new NetworkCredential(proxy.AuthUsername, proxy.AuthPassword)
    }
};
var httpClient = new HttpClient(handler);
```

### HTTP REST API Usage

#### Get Proxy (Simple)

**Endpoint**: `POST /api/resource-pool/v1/ProxyPool/get`

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

var response = await client.ExecuteAsync<ProxyResponse>(request);
var proxy = response.Data.Proxy;

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

#### 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:**

| 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ố**

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

**🎯 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ụ**:
```json
{
  "access_token": "your-token",
  "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ụ**:
```json
{
  "access_token": "your-token",
  "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ụ**:
```json
{
  "access_token": "your-token",
  "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ụ**:
```json
{
  "access_token": "your-token",
  "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ụ**:
```json
{
  "access_token": "your-token",
  "target_domain": "instagram.com",
  "type": "http",
  "strategy": "adaptive_ranking",
  "country": "JP"
}
```

**📤 Response Format**

```json
{
  "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:**
```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(
    "http://10.9.3.70:31249/api/resource-pool/v1/ProxyPool/get-v2", 
    request
);

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

// Sử dụng proxy với HttpClient
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",
    Country = "US"
});

var response = await client.ExecuteAsync<ProxyResponse>(request);
var proxy = response.Data.Proxy;

var proxyObj = new WebProxy($"{proxy.Host}:{proxy.Port}")
{
    Credentials = new NetworkCredential(proxy.AuthUsername, proxy.AuthPassword)
};

var restClient = new RestClient("https://api.example.com")
{
    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

- 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](./docs/src/HttpToSocks5Proxy/README.md).

---

## SmartPool (New System)

For the new intelligent proxy management system with SDK client, see:
- **[SmartPool SDK Documentation](./docs/src/Icomm.SmartPool.Proxy/README.md)**
- **[SmartPool API Documentation](./docs/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)