ResourcePool.Docs/SMARTPOOL_QUICK_REFERENCE.md

SmartPool Quick Reference

Tài liệu tham khảo nhanh cho SmartPool system.

🚀 Quick Start

# 1. Setup ClickHouse
clickhouse-client < src/Icomm.API.SmartPool/clickhouse_init.sql

# 2. Start Redis
redis-server

# 3. Run API
cd src/Icomm.API.SmartPool
dotnet run

# 4. Run Tests
cd src/Icomm.SmartPool.Tests
dotnet test

📦 NuGet Packages

API Backend

<PackageReference Include="MagicOnion.Server" Version="5.1.11" />
<PackageReference Include="ClickHouse.Client" Version="7.7.0" />
<PackageReference Include="EasyCaching.Redis" Version="1.9.2" />
<PackageReference Include="Dapper" Version="2.1.35" />
<PackageReference Include="Serilog.AspNetCore" Version="8.0.1" />

Client SDK

<PackageReference Include="MagicOnion.Client" Version="5.1.11" />
<PackageReference Include="Grpc.Net.Client" Version="2.60.0" />

🎯 Strategies Cheat Sheet

Strategy	Use Case	Required Params	Best For
random	General purpose	-	Simple crawling
round_robin	Load balancing	-	Distributed workload
least_delay	Speed optimization	targetDomain	Fast response needed
adaptive_ranking	Reliability	targetDomain	High success rate needed
alternative	Failover	refererProxy	Retry with similar proxy

📝 Code Snippets

Client Setup

// Program.cs
services.AddSmartPoolClient(configuration);

// Usage
public class MyService
{
    private readonly ISmartPoolClient _client;
    
    public MyService(ISmartPoolClient client) => _client = client;
    
    public async Task DoWork()
    {
        var proxy = await _client.GetProxyAsync(strategy: "least_delay");
        // Use proxy...
    }
}

Get Proxy (Simple)

var proxy = await _smartPoolClient.GetProxyAsync(
    strategy: "random",
    ipVersion: "v6",
    country: "US"
);

Get Proxy (Advanced)

var request = new GetProxyRequest
{
    AccessToken = "your-token",
    Strategy = "adaptive_ranking",
    TargetDomain = "facebook.com",
    IpVersion = "v6",
    Protocol = "http",
    Country = "US"
};
var proxy = await _smartPoolClient.GetRawProxyAsync(request);

Log Usage

await _smartPoolClient.LogProxyUsageAsync(
    accessToken: "your-token",
    proxyId: 123,
    targetDomain: "facebook.com",
    statusCode: 200,
    responseTimeMs: 450
);

Use with HttpClient

var proxy = await _smartPoolClient.GetProxyAsync();
var handler = new HttpClientHandler { Proxy = proxy };
var httpClient = new HttpClient(handler);
var response = await httpClient.GetAsync("https://example.com");

🔌 API Endpoints

HTTP REST

# Get Proxy
POST /api/smart-pool/v1/SmartProxy/get-proxy
Content-Type: application/json

{
  "accessToken": "token",
  "strategy": "least_delay",
  "targetDomain": "facebook.com"
}

# Log Usage
POST /api/smart-pool/v1/SmartProxy/log-usage
Content-Type: application/json

{
  "accessToken": "token",
  "proxyId": 123,
  "targetDomain": "facebook.com",
  "statusCode": 200,
  "responseTimeMs": 450
}

# Health Check
GET /api/smart-pool/v1/SmartProxy/health

# Get Strategies
GET /api/smart-pool/v1/SmartProxy/strategies

gRPC

var channel = GrpcChannel.ForAddress("http://localhost:5001");
var client = MagicOnionClient.Create<ISmartProxyService>(channel);

var response = await client.GetProxy(new GetProxyRequest { ... });
await client.LogProxyUsage(new ProxyUsageLogRequest { ... });
var status = await client.Ping();

🗄️ ClickHouse Queries

View Proxy Stats

SELECT 
    proxy_id,
    avgMerge(avg_response_time_state) as avg_time,
    sumIfMerge(success_count_state) / countMerge(request_count_state) as success_rate
FROM smart_pool_logs.proxy_stats_hourly
WHERE access_token = 'your-token'
    AND hour >= now() - INTERVAL 24 HOUR
GROUP BY proxy_id
ORDER BY success_rate DESC;

View Recent Logs

SELECT *
FROM smart_pool_logs.proxy_usage_logs
WHERE access_token = 'your-token'
    AND timestamp >= now() - INTERVAL 1 HOUR
ORDER BY timestamp DESC
LIMIT 100;

Add Proxy

INSERT INTO smart_pool_meta.proxy_metadata 
(id, host, port, protocol, ip_version, country, status)
VALUES 
(1, '192.168.1.100', 8080, 'http', 'v4', 'VN', 1);

Add Access Mapping (Cluster-based)

INSERT INTO smart_pool_meta.proxy_access_mapping 
(access_token, cluster, priority)
VALUES 
('your-token', 'cluster_vn_http', 10);

⚙️ Configuration Templates

appsettings.json (API)

{
  "ClickHouse": {
    "Host": "localhost",
    "Port": 8123,
    "MetaDatabase": "smart_pool_meta",
    "LogsDatabase": "smart_pool_logs",
    "Username": "default",
    "Password": ""
  },
  "Redis": {
    "Configuration": "localhost:6379"
  },
  "Kestrel": {
    "Endpoints": {
      "Http": { "Url": "http://0.0.0.0:5000" },
      "Grpc": { "Url": "http://0.0.0.0:5001", "Protocols": "Http2" }
    }
  }
}

appsettings.json (Client)

{
  "SmartPool": {
    "Protocol": "Grpc",
    "Host": "localhost",
    "Port": 5001,
    "UseSecureConnection": false,
    "DefaultAccessToken": "your-token",
    "TimeoutMs": 30000
  }
}

🐛 Troubleshooting

Proxy không available

var proxy = await _client.GetProxyAsync();
if (proxy == null)
{
    // Check:
    // 1. Access token có đúng không?
    // 2. Có proxy nào được map với token này không?
    // 3. Filters có quá strict không?
}

Connection timeout

// Tăng timeout
services.AddSmartPoolClient(options =>
{
    options.TimeoutMs = 60000; // 60 seconds
});

Strategy không hoạt động

// Check logs có đủ không (cho least_delay, adaptive_ranking)
// Cần ít nhất 10 logs để adaptive_ranking hoạt động

📊 Performance Tips

1. Use gRPC for production - Faster than HTTP
2. Log asynchronously - Don't block main flow
3. Cache proxy info - Reduce API calls
4. Use appropriate strategy - Match use case
5. Monitor ClickHouse - Check query performance

🔒 Security Notes

• Always use HTTPS in production
• Rotate access tokens regularly
• Limit proxy access by token
• Monitor unusual usage patterns
• Set appropriate TTL for logs

📚 Documentation Links

• Main README
• API Backend Guide
• Client SDK Guide
• Usage Examples
• Implementation Summary

🆘 Support

For issues or questions:

1. Check logs in logs/smartpool-*.log
2. Verify ClickHouse connection
3. Check Redis connection
4. Review configuration
5. Contact development team

---

Version: 1.0.0
Last Updated: 2026-01-22