nthbouncer
Log inGet started

Acquire a concurrency lock without proxying

Goal

Share the same pool concurrency limit and keys as proxy traffic, but perform the upstream HTTP call from your own process. Typical cases: a connector that cannot rewrite the base URL, or a worker that must keep the origin client library as-is.

Full request and response shapes live in the Concurrency locks API.

Pattern

  1. Acquire a slot on https://api.nthpool.cloud (not the pool proxy host).
  2. Call the upstream yourself while holding the slot.
  3. Renew about every 10 seconds if the work can exceed one lease term.
  4. Release when finished. Include throttle fields if the upstream returned 429 so adaptive / RPM control can learn.
export POOL_KEY='nb_live_…'
export LOCK_API='https://api.nthpool.cloud/pools/your-pool/lock'

# Fail fast when the pool is full; add "waitMs" to join the queue.
GRANT=$(curl -sS -X POST "$LOCK_API/acquire" \
  -H "X-Nthpool-Key: $POOL_KEY" \
  -H "Content-Type: application/json")
SLOT_ID=$(printf '%s' "$GRANT" | jq -r .slotId)

# … your upstream call …

curl -sS -X POST "$LOCK_API/$SLOT_ID/release" \
  -H "X-Nthpool-Key: $POOL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":200}'

Auth and credentials

Use the same pool key (and optional HMAC / JWT / Cloudflare Access) as the proxy. The lock API never emits managed upstream credentials. On a managed pool you still supply origin auth yourself when you call the upstream.

See also