ResourcePool.Docs/docs/src/Icomm.SmartPool.Proxy/QUICK_REFERENCE.md

SmartPool SDK - Quick Reference

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

📦 Installation

1. Install NuGet Package

dotnet add package --source ic --version 10.0.1 Icomm.SmartPool.Proxy

Hoặc trong .csproj:

<ItemGroup>
  <PackageReference Include="Icomm.SmartPool.Proxy" Version="10.0.1" />
</ItemGroup>

2. Register in DI Container

using Icomm.SmartPool.Proxy.Extensions;

// In Startup.cs or Program.cs
services.AddSmartPoolClient(configuration);

3. Inject và sử dụng

public class MyService
{
    private readonly ISmartPoolClient _client;
    public MyService(ISmartPoolClient client) => _client = client;
}

⚡ Quick Start

// Lấy proxy
var proxy = await _client.GetProxyAsync(new GetProxyRequest
{
    strategy = "least_delay",
    target_domain = "facebook.com"
});

// Sử dụng với HttpClient
var handler = new HttpClientHandler { Proxy = proxy };
var httpClient = new HttpClient(handler);
var response = await httpClient.GetAsync("https://facebook.com");

// Log usage (fire-and-forget)
_ = _client.LogProxyUsageAsync(new ProxyUsageLogRequest
{
    proxy_id = 123,
    target_domain = "facebook.com",
    status_code = (int)response.StatusCode,
    response_time_ms = 450
});

🎯 Strategies

Strategy	Use Case	Required Fields
random	General purpose	-
round_robin	Balanced distribution	-
least_delay	Performance critical	target_domain
adaptive_ranking	Reliability critical	target_domain
alternative	Retry scenarios	referer_proxy

⚙️ Configuration Presets

// High Performance (scraping)
services.AddSmartPoolClientHighPerformance(configuration);

// Low Latency (realtime)
services.AddSmartPoolClientLowLatency(configuration);

// Custom
services.AddSmartPoolClient(configuration, options =>
{
    options.EnableClientCache = true;
    options.ClientCacheDurationSeconds = 60;
    options.EnableBatchLogging = true;
});

📝 Common Patterns

Pattern 1: Simple Request

var proxy = await _client.GetProxyAsync();
var handler = new HttpClientHandler { Proxy = proxy };
var httpClient = new HttpClient(handler);
var response = await httpClient.GetAsync(url);

Pattern 2: With Retry

SmartProxyServer? currentProxy = null;
for (int i = 0; i < 3; i++)
{
    currentProxy = await _client.GetRawProxyAsync(
        i == 0 
            ? new GetProxyRequest { strategy = "least_delay" }
            : new GetProxyRequest { 
                strategy = "alternative", 
                referer_proxy = currentProxy 
            }
    );
    // ... use proxy
}

Pattern 3: Batch Processing

foreach (var url in urls)
{
    var proxy = await _client.GetProxyAsync();
    // ... use proxy
    
    // Queue log (non-blocking)
    _client.QueueLogProxyUsage(new ProxyUsageLogRequest { /* ... */ });
}

🔧 Configuration Options

{
  "SmartPool": {
    "Protocol": "Grpc",                    // "Grpc" | "Http"
    "Host": "localhost",
    "Port": 5001,
    "TimeoutMs": 30000,
    
    "EnableClientCache": true,             // Cache proxy results
    "ClientCacheDurationSeconds": 30,
    
    "EnableFireAndForgetLogging": true,    // Non-blocking logs
    "EnableBatchLogging": true,             // Batch log requests
    "LogBatchSize": 50,
    
    "EnableCompression": true,              // Response compression
    "CompressionAlgorithm": "gzip"
  }
}

🚀 Performance Tips

1. ✅ Use gRPC protocol (faster than HTTP)
2. ✅ Enable ClientCache for random/round_robin strategies
3. ✅ Use QueueLogProxyUsage() for high-throughput
4. ✅ Use least_delay strategy for performance-critical scenarios
5. ✅ Set appropriate TimeoutMs based on network

📚 Full Documentation

• SDK Documentation - Chi tiết đầy đủ
• System README - Tổng quan hệ thống