Using sticky sessions

KeyValueTTLExamples
sessionAny unique identifier of up to 255 characters (regardless of character encoding); Massive will make best efforts to route requests in the same session to the same egress node15 minutessession42, 1234

You can inject a session identifier, like a unique representation of your app or active task, to specify that multiple requests should originate from a single egress node (if available):

curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-37:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
  • Session TTL is 15 minutes. Every request with a session key prolongs the session and refreshes its TTL.
  • When a session identifier is specified and found the server will perform a request via the same node unless:
    • TTL is expired.
    • The request limit per minute for the node is exceeded.
    • The node has gone offline.
  • If the session identifier is not found or the conditions above are not met, a new session is created with the specified ID and attached to the new node.

Additional parameters

KeyValue
sessionmodestrict, flex

By default, when a sticky session fails, our algorithm attempts to find a new node to complete the request, attaching a new IP address to the sticky session. This behavior can be overwritten by specifying sessionmode-flex.

Example of using undefined sessionmode, which defaults to sessionmode-strict:

curl -x https://network.joinmassive.com:65535 -U '{PROXY_USERNAME}-session-123:{API_KEY}' https://cloudflare.com/cdn-cgi/trace

Example with sessionmode-strict explicitly defined:

curl -x https://network.joinmassive.com:65535 -U '{PROXY_USERNAME}-session-123-sessionmode-strict:{API_KEY}' https://cloudflare.com/cdn-cgi/trace

Alternatively, a sticky session can persist through an error by using sessionmode-flex, though this may increase error rate.

Attention: The max number of errors is 15 until a new node is assigned to a sticky session.

Example with sessionmode-flex:

curl -x https://network.joinmassive.com:65535 -U '{PROXY_USERNAME}-session-123-sessionmode-flex:{API_KEY}' https://cloudflare.com/cdn-cgi/trace

Known issues

When session is specified without geotargeting or use of one of our regional endpoints, the request may get cross routed, causing different IPs to be called during a sticky session depending on which server handles the request.

Workarounds:

  1. Use regional endpoints https://us-network.joinmassive.com/ or https://eu-network.joinmassive.com/
curl -x https://us-network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-session-123:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
  1. Use geotargeting
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-country-US-session-123:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace