Sessions & sticky IPs

Some workflows need the same IP across several requests: logging in, paginating behind a session cookie, or completing a checkout. bytetourist supports this with session affinity.

How it works

Pick a stable session id and route with the session_affinity strategy (other strategies ignore session). bytetourist pins that session to a node and keeps using it until the session has gone 30 minutes without a request:

# request 1 and request 2 leave from the same node
curl -k -x http://dev.bytetourist.com:8080 \
  -U "YOUR_API_KEY-strategy-session_affinity-session-checkout_42:" \
  https://shop.example.com/cart

curl -k -x http://dev.bytetourist.com:8080 \
  -U "YOUR_API_KEY-strategy-session_affinity-session-checkout_42:" \
  https://shop.example.com/checkout

Or use headers. On an HTTPS target they must go on the CONNECT, so in curl use --proxy-header:

--proxy-header "X-Proxy-Strategy: session_affinity" --proxy-header "X-Proxy-Session: checkout_42"

Choosing session ids

Use a unique id per logical session (per user, per cart, per crawl worker).
Reuse the same id for every request that must share a node.
Don’t put - in an id sent in the username: the username is split on -, so session-checkout-42 would become checkout. Use _ instead.
Combine with targeting, e.g. pin a session to a node in one country:

-U "YOUR_API_KEY-cc-de-strategy-session_affinity-session-u_8841:"

When the pinned node goes away

If the pinned node leaves the fleet (e.g. it’s recycled by autoscaling) or is demoted for failing against the target, the session is re-pinned to another eligible node; strict-true doesn’t change that. While the pinned node’s circuit breaker is open, or it’s at its concurrency limit for the target, single requests can go to another node. Pins live in the proxy’s memory, so a restart drops them. Long-lived sessions should tolerate an occasional IP change.