Sync README files from source repository [skip ci]

2026-01-26 06:30:48 +00:00
parent 4e7b46e058
commit 135e7c33b1
21 changed files with 6733 additions and 4 deletions
@@ -0,0 +1,169 @@
+# SmartPool SDK - Quick Reference
+
+Tài liệu tham khảo nhanh cho SmartPool SDK.
+
+## 📦 Installation
+
+### 1. Install NuGet Package
+
+```bash
+dotnet add package --source ic --version 10.0.1 Icomm.SmartPool.Proxy
+```
+
+Hoặc trong `.csproj`:
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Icomm.SmartPool.Proxy" Version="10.0.1" />
+</ItemGroup>
+```
+
+### 2. Register in DI Container
+
+```csharp
+using Icomm.SmartPool.Proxy.Extensions;
+
+// In Startup.cs or Program.cs
+services.AddSmartPoolClient(configuration);
+```
+
+### 3. Inject và sử dụng
+
+```csharp
+public class MyService
+{
+    private readonly ISmartPoolClient _client;
+    public MyService(ISmartPoolClient client) => _client = client;
+}
+```
+
+## ⚡ Quick Start
+
+```csharp
+// 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
+
+```csharp
+// 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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+foreach (var url in urls)
+{
+    var proxy = await _client.GetProxyAsync();
+    // ... use proxy
+    
+    // Queue log (non-blocking)
+    _client.QueueLogProxyUsage(new ProxyUsageLogRequest { /* ... */ });
+}
+```
+
+## 🔧 Configuration Options
+
+```json
+{
+  "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](./SDK_DOCUMENTATION.md)** - Chi tiết đầy đủ
+- **[System README](../../SMARTPOOL_README.md)** - Tổng quan hệ thống