ResourcePool.Docs/SMARTPOOL_TROUBLESHOOTING.md

SmartPool Troubleshooting Guide

Problem: "No proxy available matching criteria"

Quick Fix

# 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

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

-- Should show:
-- smart_pool_meta
-- smart_pool_logs

Step 2: Check Tables

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

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

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

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

{
  "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:

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

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

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:

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

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

Solution:

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

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

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

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

With Strategy

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

# 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

{
  "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

{
  "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:

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

Debug Queries

Run these in clickhouse-client:

# Interactive mode
clickhouse-client

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

Key queries:

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

   {
     "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)