Skip to main content

​
Overview

Targets are the core routing config. Each inbound request is matched against the target list top-to-bottom — the first regex match handles the request. Every target has its own IP pool with independent rotation and quarantine state. At least one target is required.

​
Fields

FieldTypeDefaultDescription
namestringrequiredLabel used in logs and metrics
regexstringrequiredPython regex matched against the full request URL
ipPoolstringrequired*Name of a shared ipPools entry
ipListlistrequired*Inline proxy addresses — host:port or bare host
defaultProxyPortint8080Port applied to bare IPs in ipList
minRequestIntervalduration1sHow long an IP is held off the pool after any request
maxQueueWaitduration30sHow long a request waits for a free IP before failing
numRetriesint3Retry attempts on failure, each using a different IP
ipFailuresUntilQuarantineint5Consecutive failures before an IP is quarantined
quarantineTimeduration120sHow long a quarantined IP sits out before returning
* Exactly one of ipPool or ipList must be provided per target.

​
Rate limiting with minRequestInterval

minRequestInterval is the primary knob for respecting a target site’s rate limits. After any request through an IP, that IP is unavailable for this duration before being returned to the pool. 
minRequestInterval: 5s   # max 1 request per IP per 5 seconds
With 3 IPs and minRequestInterval: 1s, you can sustain ~3 requests/second to the target.

​
Retry behaviour

On a failed request (connection error, 429, 5xx), Proxy Hopper picks a different IP and retries up to numRetries times. Each retry uses a freshly acquired IP from the pool. 
numRetries: 3   # up to 3 retries = up to 4 total attempts
CONNECT tunnel mode cannot retry mid-flight failures — the client has already committed to the TLS connection. Use forwarding mode for full retry support over HTTPS.

​
Quarantine

When an IP accumulates ipFailuresUntilQuarantine consecutive failures, it is removed from the pool for quarantineTime, then automatically returned. 
ipFailuresUntilQuarantine: 5
quarantineTime: 2m
Quarantine events are tracked in Prometheus: proxy_hopper_ip_quarantine_events_total.

​
Examples

​
Single catch-all target

targets:
  - name: general
    regex: '.*'
    ipList:
      - "10.0.0.1:3128"
      - "10.0.0.2:3128"
    minRequestInterval: 1s
    maxQueueWait: 30s
    numRetries: 3
    ipFailuresUntilQuarantine: 5
    quarantineTime: 2m

​
Per-API targets with shared pool

targets:
  - name: google-apis
    regex: '.*\.googleapis\.com.*'
    ipPool: shared-pool
    minRequestInterval: 5s
    maxQueueWait: 30s
    numRetries: 3
    ipFailuresUntilQuarantine: 5
    quarantineTime: 10m

  - name: fallback
    regex: '.*'
    ipPool: shared-pool
    minRequestInterval: 1s
    maxQueueWait: 30s
    numRetries: 2
    ipFailuresUntilQuarantine: 3
    quarantineTime: 5m
Targets are evaluated top-to-bottom — google-apis matches first for Google API URLs; everything else falls through to fallback.