ResourcePool.Docs/SMARTPOOL_TROUBLESHOOTING.md

# SmartPool Troubleshooting Guide

## Problem: "No proxy available matching criteria"

### Quick Fix

```bash
# 1. Initialize database
clickhouse-client < src/Icomm.API.SmartPool/clickhouse_init.sql

# 2. Add test data
clickhouse-client < src/Icomm.API.SmartPool/clickhouse_test_data.sql

# 3. Test API
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
  -H 'Content-Type: application/json' \
  -d '{"accessToken": "test"}'
```

## Diagnosis Steps

### Step 1: Verify Database Setup

```sql
-- Check databases exist
SHOW DATABASES LIKE '%smart_pool%';

-- Should show:
-- smart_pool_meta
-- smart_pool_logs
```

### Step 2: Check Tables

```sql
-- Check meta tables
SHOW TABLES FROM smart_pool_meta;

-- Should show:
-- proxy_metadata
-- proxy_access_mapping

-- Check data count
SELECT count() FROM smart_pool_meta.proxy_metadata;
SELECT count() FROM smart_pool_meta.proxy_access_mapping;
```

### Step 3: Verify Proxy Data

```sql
-- Check proxies
SELECT 
    id, 
    host, 
    port, 
    protocol, 
    cluster, 
    status 
FROM smart_pool_meta.proxy_metadata FINAL 
LIMIT 10;

-- Check active proxies
SELECT 
    status,
    count() as count
FROM smart_pool_meta.proxy_metadata FINAL
GROUP BY status;
```

### Step 4: Verify Access Mappings

```sql
-- Check your access_token mappings
SELECT * 
FROM smart_pool_meta.proxy_access_mapping FINAL 
WHERE access_token = 'YOUR_TOKEN';

-- Check all mappings
SELECT 
    access_token,
    cluster,
    count() as count
FROM smart_pool_meta.proxy_access_mapping FINAL
GROUP BY access_token, cluster;
```

### Step 5: Test the JOIN Query

```sql
-- This is the query SmartPool uses internally
SELECT 
    m.id,
    m.host,
    m.port,
    m.protocol,
    m.cluster
FROM smart_pool_meta.proxy_metadata FINAL m
INNER JOIN smart_pool_meta.proxy_access_mapping FINAL a 
    ON m.cluster = a.cluster
WHERE a.access_token = 'test'  -- Replace with your token
    AND m.status = 1
ORDER BY m.id;
```

## Common Issues

### Issue 1: Empty Result Set

**Symptoms:**
```json
{
  "proxy": null,
  "message": "No proxy available matching criteria",
  "success": false
}
```

**Causes:**
1. No data in database
2. Access token not mapped to any cluster
3. All proxies are inactive (status = 0)
4. Cluster names don't match between tables

**Solution:**
```bash
# Add test data
clickhouse-client < src/Icomm.API.SmartPool/clickhouse_test_data.sql
```

### Issue 2: Wrong Access Token

**Symptoms:**
- Query returns empty but data exists

**Check:**
```sql
-- See which tokens have access
SELECT DISTINCT access_token 
FROM smart_pool_meta.proxy_access_mapping FINAL;
```

**Solution:**
Use one of the existing tokens or add a new mapping:
```sql
INSERT INTO smart_pool_meta.proxy_access_mapping (access_token, cluster)
VALUES ('your_token', 'cluster_vn_http');
```

### Issue 3: No Proxies in Cluster

**Symptoms:**
- Mapping exists but no proxies returned

**Check:**
```sql
-- Find orphaned mappings
SELECT 
    a.access_token,
    a.cluster,
    count(m.id) as proxy_count
FROM smart_pool_meta.proxy_access_mapping FINAL a
LEFT JOIN smart_pool_meta.proxy_metadata FINAL m 
    ON a.cluster = m.cluster AND m.status = 1
GROUP BY a.access_token, a.cluster
HAVING proxy_count = 0;
```

**Solution:**
Add proxies to the cluster or change mapping to existing cluster.

### Issue 4: Proxies Inactive

**Check:**
```sql
-- Check inactive proxies
SELECT 
    cluster,
    count() as inactive_count
FROM smart_pool_meta.proxy_metadata FINAL
WHERE status = 0
GROUP BY cluster;
```

**Solution:**
```sql
-- Activate all proxies in a cluster
ALTER TABLE smart_pool_meta.proxy_metadata
UPDATE status = 1
WHERE cluster = 'cluster_vn_http';
```

### Issue 5: Cluster Name Mismatch

**Check:**
```sql
-- Clusters in proxy_metadata
SELECT DISTINCT cluster 
FROM smart_pool_meta.proxy_metadata FINAL;

-- Clusters in proxy_access_mapping
SELECT DISTINCT cluster 
FROM smart_pool_meta.proxy_access_mapping FINAL;

-- Find mismatches
SELECT cluster, 'In mapping but not in metadata' as issue
FROM smart_pool_meta.proxy_access_mapping FINAL
WHERE cluster NOT IN (
    SELECT DISTINCT cluster 
    FROM smart_pool_meta.proxy_metadata FINAL
);
```

**Solution:**
Fix cluster names to match:
```sql
-- Update cluster name in metadata
ALTER TABLE smart_pool_meta.proxy_metadata
UPDATE cluster = 'cluster_vn_http'
WHERE cluster = 'old_cluster_name';
```

## Testing with cURL

### Basic Request (No Filters)

```bash
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
  -H 'Content-Type: application/json' \
  -d '{
    "accessToken": "test"
  }'
```

### With Strategy

```bash
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
  -H 'Content-Type: application/json' \
  -d '{
    "accessToken": "test",
    "strategy": "random"
  }'
```

### With Filters

```bash
# Filter by country
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
  -H 'Content-Type: application/json' \
  -d '{
    "accessToken": "test",
    "country": "VN"
  }'

# Filter by protocol
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
  -H 'Content-Type: application/json' \
  -d '{
    "accessToken": "test",
    "protocol": "socks5"
  }'

# Multiple filters
curl -X POST 'http://localhost:5000/api/smart-pool/v1/SmartProxy/get-proxy' \
  -H 'Content-Type: application/json' \
  -d '{
    "accessToken": "test",
    "strategy": "least_delay",
    "country": "US",
    "protocol": "http",
    "ipVersion": "v4",
    "targetDomain": "example.com"
  }'
```

## Expected Responses

### Success Response

```json
{
  "proxy": {
    "id": 1,
    "host": "103.90.227.1",
    "port": 8080,
    "protocol": "http",
    "ipVersion": "v4",
    "country": "VN",
    "location": "Hanoi",
    "authUsername": "",
    "authPassword": "",
    "cluster": "cluster_vn_http",
    "source": "manual",
    "description": "Vietnam HTTP proxy 1",
    "status": 1
  },
  "message": null,
  "success": true
}
```

### Error Response

```json
{
  "proxy": null,
  "message": "No proxy available matching criteria",
  "success": false
}
```

## Filter Logic

SmartPool uses **optional filters** - if a filter is not provided, it won't be applied:

| Filter | Behavior if Empty/Null |
|--------|----------------------|
| `accessToken` | **Required** - returns error if missing |
| `strategy` | Defaults to `"random"` |
| `targetDomain` | Not filtered - returns all proxies |
| `ipVersion` | Not filtered - returns v4 and v6 |
| `protocol` | Not filtered - returns http, socks5, etc. |
| `country` | Not filtered - returns all countries |
| `refererProxy` | Only used in "alternative" strategy |

**Example:**
```json
{
  "accessToken": "test"
  // No filters = returns ALL proxies accessible by 'test' token
}
```

## Debug Queries

Run these in `clickhouse-client`:

```bash
# Interactive mode
clickhouse-client

# Or load debug script
clickhouse-client < src/Icomm.API.SmartPool/clickhouse_debug.sql
```

Key queries:

```sql
-- See everything accessible by a token
SELECT 
    m.*
FROM smart_pool_meta.proxy_metadata FINAL m
INNER JOIN smart_pool_meta.proxy_access_mapping FINAL a 
    ON m.cluster = a.cluster
WHERE a.access_token = 'test'
    AND m.status = 1;

-- Count by cluster
SELECT 
    a.cluster,
    count(m.id) as proxy_count
FROM smart_pool_meta.proxy_access_mapping FINAL a
LEFT JOIN smart_pool_meta.proxy_metadata FINAL m 
    ON a.cluster = m.cluster AND m.status = 1
WHERE a.access_token = 'test'
GROUP BY a.cluster;
```

## Getting Help

If you're still having issues:

1. Check application logs: `logs/smartpool-*.log`
2. Check ClickHouse logs
3. Enable debug logging in `appsettings.json`:
   ```json
   {
     "Serilog": {
       "MinimumLevel": {
         "Default": "Debug"
       }
     }
   }
   ```
4. Run all diagnostic queries in `clickhouse_debug.sql`
5. Share the output for further assistance

## Quick Reference

| File | Purpose |
|------|---------|
| `clickhouse_init.sql` | Initialize database schema |
| `clickhouse_test_data.sql` | Add sample data for testing |
| `clickhouse_debug.sql` | Diagnostic queries |
| `README.md` | Full documentation |
| `logs/smartpool-*.log` | Application logs |

## Test Access Tokens

After running `clickhouse_test_data.sql`, these tokens are available:

| Token | Access |
|-------|--------|
| `test` | All clusters (10 proxies) |
| `user1_token` | VN clusters only (3 proxies) |
| `user2_token` | US + Global (4 proxies) |
| `user3_token` | JP clusters only (2 proxies) |