05_test_residential_proxy.py

"""
Health-check a generated residential proxy.

Routes a request through the proxy to https://ipapi.co/json/ and reports:
  - exit IP and reverse DNS
  - country, region, city, ASN/org
  - round-trip latency

If the reported country does not match your targeting, something is wrong
(targeting code mistake, country out of stock, sub-user out of bandwidth).
"""
import time

import requests

from proxyshard import (
    ProxyshardClient, build_residential_username, build_proxy_url, RELAY_HOSTS,
)


def probe(proxy_url: str, timeout: int = 20) -> dict:
    start = time.perf_counter()
    r = requests.get(
        "https://ipapi.co/json/",
        proxies={"http": proxy_url, "https": proxy_url},
        timeout=timeout,
    )
    latency_ms = (time.perf_counter() - start) * 1000
    r.raise_for_status()
    data = r.json()
    data["_latency_ms"] = round(latency_ms)
    return data


def main() -> None:
    client = ProxyshardClient()

    PROXY_TYPE = "premium"
    COUNTRY = "de"

    subs = client.residential_subusers(proxy_type=PROXY_TYPE, limit=1)
    if not subs:
        raise SystemExit(f"No {PROXY_TYPE} sub-users — create one first.")

    username = build_residential_username(PROXY_TYPE, country=COUNTRY, sticky=True)
    proxy_url = build_proxy_url(username, subs[0]["proxy_password"], host=RELAY_HOSTS["eu"])

    print(f"Testing  {proxy_url.split('@')[1]}  (country={COUNTRY})\n")

    try:
        info = probe(proxy_url)
    except requests.RequestException as e:
        print(f"FAILED: {e}\n")
        print("Possible causes:")
        print("  1. Stale sticky session: the exit device left the pool. Generate a new sid.")
        print("  2. Sub-user bandwidth exhausted: check 02_list_residential_subusers.py.")
        print("  3. Country out of stock: try a neighbouring country or country='any'.")
        print("  4. Still stuck? Reach us on live chat at https://proxyshard.com and we'll help.")
        return

    expected_ok = info.get("country_code", "").lower() == COUNTRY.lower()
    print(f"  IP:        {info.get('ip')}")
    print(f"  Country:   {info.get('country_name')} ({info.get('country_code')})  "
          f"{'OK' if expected_ok else 'MISMATCH'}")
    print(f"  Region:    {info.get('region')}")
    print(f"  City:      {info.get('city')}")
    print(f"  Org:       {info.get('org')}")
    print(f"  ASN:       {info.get('asn')}")
    print(f"  Latency:   {info['_latency_ms']} ms")


if __name__ == "__main__":
    main()