From ad923025e868a71dcf6edcb788bc7d7eda0897d3 Mon Sep 17 00:00:00 2001 From: Valentyn Naboka Date: Mon, 16 Mar 2026 14:33:31 +0100 Subject: [PATCH 1/6] docs: add norotate session mode documentation Document the new norotate session mode (PROXY-263) across sticky session docs and knowledge base articles. Includes behavior description, curl examples, 502 error semantics, and warning about auth string re-parsing. --- .../how-do-i-implement-sticky-sessions.mdx | 12 +++++- .../when-do-sticky-sessions-change-nodes.mdx | 3 +- residential/sticky-sessions.mdx | 40 +++++++++++++++++-- 3 files changed, 48 insertions(+), 7 deletions(-) diff --git a/kb/technical/how-do-i-implement-sticky-sessions.mdx b/kb/technical/how-do-i-implement-sticky-sessions.mdx index 37dc61b..077b4e8 100644 --- a/kb/technical/how-do-i-implement-sticky-sessions.mdx +++ b/kb/technical/how-do-i-implement-sticky-sessions.mdx @@ -20,5 +20,13 @@ Parameters Explained: - session-37: Unique session identifier - sessionttl-30: 30-minute session duration -- sessionmode-flex: Flexible session mode -- Port 65535: HTTPS (Use 65534 for HTTP, 65533 for SOCKS5) \ No newline at end of file +- sessionmode-flex: Flexible session mode (also supports `strict` and `norotate`) +- Port 65535: HTTPS (Use 65534 for HTTP, 65533 for SOCKS5) + +No-Rotate Example (fails with 502 instead of rotating): + +```bash +curl -x https://network.joinmassive.com:65535 \ +-U '{USERNAME}-session-37-sessionttl-30-sessionmode-norotate:{PASSWORD}' \ +https://cloudflare.com/cdn-cgi/trace +``` \ No newline at end of file diff --git a/kb/technical/when-do-sticky-sessions-change-nodes.mdx b/kb/technical/when-do-sticky-sessions-change-nodes.mdx index e3fec36..f6c6e9a 100644 --- a/kb/technical/when-do-sticky-sessions-change-nodes.mdx +++ b/kb/technical/when-do-sticky-sessions-change-nodes.mdx @@ -9,4 +9,5 @@ Sessions may change under these conditions: 3. Node unavailability 4. Mode-specific conditions: - Flex Mode: After 15 consecutive errors - - Strict Mode: Immediate change on failure \ No newline at end of file + - Strict Mode: Immediate change on failure + - No-Rotate Mode: Never changes nodes — returns 502 instead \ No newline at end of file diff --git a/residential/sticky-sessions.mdx b/residential/sticky-sessions.mdx index 9f91673..8b699f0 100644 --- a/residential/sticky-sessions.mdx +++ b/residential/sticky-sessions.mdx @@ -39,13 +39,13 @@ When a session identifier is specified and found, the server will perform a requ * The node has gone offline * Error limit is reached (in flex mode) -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 a new node. +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 a new node. In **norotate** mode, no new session is created — the request fails with a **502** error instead. ## Session Modes | Key | Value | Description | | ----------- | ---------------- | ----------- | -| sessionmode | `strict`, `flex` | Controls session behavior on errors | +| sessionmode | `strict`, `flex`, `norotate` | Controls session behavior on errors | ### Strict Mode (Default) @@ -87,6 +87,34 @@ curl -x https://network.joinmassive.com:65535 \ https://cloudflare.com/cdn-cgi/trace ``` +### No-Rotate Mode + +Sessions can operate in **norotate mode** where sessions are never rotated to a new node. If the assigned node becomes unavailable or any error occurs, the request fails with a **502** error instead of rotating to a new node. This is useful when IP consistency is critical and you would rather fail than silently switch IPs. + +- Sessions never rotate to a new node +- Returns **502** on node failure, TTL expiry, or rate limit instead of assigning a new node +- Guarantees that a given session ID always maps to the same node or fails + + + **Consistent auth strings required:** Session parameters (including `sessionmode`) are re-parsed from the auth string on every request. If you omit `sessionmode-norotate` on a subsequent request using the same session ID, the session silently falls back to **strict** mode and may rotate to a new node on failure. Always include `sessionmode-norotate` in every request for the session. + + +Example with `sessionmode-norotate`: + +```bash +curl -x https://network.joinmassive.com:65535 \ + -U '{PROXY_USERNAME}-session-123-sessionmode-norotate:{API_KEY}' \ + https://cloudflare.com/cdn-cgi/trace +``` + +Example combining norotate with a custom TTL: + +```bash +curl -x https://network.joinmassive.com:65535 \ + -U '{PROXY_USERNAME}-session-123-sessionmode-norotate-sessionttl-60:{API_KEY}' \ + https://cloudflare.com/cdn-cgi/trace +``` + ## Additional Parameters | Key | Value | Description | Default | @@ -108,7 +136,7 @@ This example allows up to 5 consecutive errors before rotating to a new node. ## Best Practices 1. **Plan TTL appropriately**: Since sessions use static TTL (not extended by activity), set an appropriate duration for your use case -2. **Choose the right mode**: Default strict mode ensures immediate rotation on any error; use flex mode if you need IP stability +2. **Choose the right mode**: Default strict mode ensures immediate rotation on any error; use flex mode if you need IP stability; use norotate mode if you need guaranteed IP consistency and prefer failures over silent rotation 3. **Monitor error rates**: Adjust `sessionerr` based on your tolerance for retries (default is 15) 4. **Session ID naming**: Use descriptive session IDs to help with debugging and monitoring @@ -118,12 +146,16 @@ This example allows up to 5 consecutive errors before rotating to a new node. The following parameters are only applied when a session is created or rotated, not on existing sessions: - `sessionttl` - TTL duration - - `sessionmode` - Strict vs flex behavior + - `sessionmode` - Strict, flex, or norotate behavior - `sessionerr` - Error limit for flex mode - Geographic parameters (`subdivision`, `zipcode`, etc.) This means changing these parameters on subsequent requests with the same session ID will have no effect until the session rotates to a new node. + + **Runtime re-parsing:** Session parameters are re-parsed from the auth string on every request. If you omit a parameter like `sessionmode-norotate` on a subsequent request, the session silently reverts to the default behavior (strict mode). Always use consistent auth strings for all requests within a session. + + ### Session-Breaking Parameters From 9e15b4e8fe379140fa93cced001f711e0b87221c Mon Sep 17 00:00:00 2001 From: Valentyn Naboka Date: Mon, 16 Mar 2026 19:14:09 +0100 Subject: [PATCH 2/6] docs: fix norotate docs to match actual implementation - Correct status codes: 502 for tunnel errors, 503 for node unavailable (was incorrectly showing 502 for all cases) - Move sessionmode out of "creation-only" params into new "re-parsed on every request" section, matching actual dispatcher behavior - Document that sessionerr is ignored in norotate mode - Fix KB article status code accuracy --- .../when-do-sticky-sessions-change-nodes.mdx | 2 +- residential/sticky-sessions.mdx | 12 +++++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/kb/technical/when-do-sticky-sessions-change-nodes.mdx b/kb/technical/when-do-sticky-sessions-change-nodes.mdx index f6c6e9a..b92e7a0 100644 --- a/kb/technical/when-do-sticky-sessions-change-nodes.mdx +++ b/kb/technical/when-do-sticky-sessions-change-nodes.mdx @@ -10,4 +10,4 @@ Sessions may change under these conditions: 4. Mode-specific conditions: - Flex Mode: After 15 consecutive errors - Strict Mode: Immediate change on failure - - No-Rotate Mode: Never changes nodes — returns 502 instead \ No newline at end of file + - No-Rotate Mode: Never changes nodes — returns 502 (tunnel error) or 503 (node unavailable) instead \ No newline at end of file diff --git a/residential/sticky-sessions.mdx b/residential/sticky-sessions.mdx index 8b699f0..8c54ad9 100644 --- a/residential/sticky-sessions.mdx +++ b/residential/sticky-sessions.mdx @@ -39,7 +39,7 @@ When a session identifier is specified and found, the server will perform a requ * The node has gone offline * Error limit is reached (in flex mode) -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 a new node. In **norotate** mode, no new session is created — the request fails with a **502** error instead. +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 a new node. In **norotate** mode, no new session is created — the request fails with a **502** or **503** error instead. ## Session Modes @@ -89,10 +89,11 @@ curl -x https://network.joinmassive.com:65535 \ ### No-Rotate Mode -Sessions can operate in **norotate mode** where sessions are never rotated to a new node. If the assigned node becomes unavailable or any error occurs, the request fails with a **502** error instead of rotating to a new node. This is useful when IP consistency is critical and you would rather fail than silently switch IPs. +Sessions can operate in **norotate mode** where sessions are never rotated to a new node. If the assigned node becomes unavailable or any error occurs, the request fails instead of rotating to a new node. This is useful when IP consistency is critical and you would rather fail than silently switch IPs. - Sessions never rotate to a new node -- Returns **502** on node failure, TTL expiry, or rate limit instead of assigning a new node +- Returns **502** on tunnel errors (node responds with an error) or **503** when the node is unavailable (gone offline or session expired) +- The `sessionerr` parameter is ignored in norotate mode — any error fails immediately - Guarantees that a given session ID always maps to the same node or fails @@ -146,14 +147,15 @@ This example allows up to 5 consecutive errors before rotating to a new node. The following parameters are only applied when a session is created or rotated, not on existing sessions: - `sessionttl` - TTL duration - - `sessionmode` - Strict, flex, or norotate behavior - `sessionerr` - Error limit for flex mode - Geographic parameters (`subdivision`, `zipcode`, etc.) This means changing these parameters on subsequent requests with the same session ID will have no effect until the session rotates to a new node. + ### Parameters Re-parsed on Every Request + - **Runtime re-parsing:** Session parameters are re-parsed from the auth string on every request. If you omit a parameter like `sessionmode-norotate` on a subsequent request, the session silently reverts to the default behavior (strict mode). Always use consistent auth strings for all requests within a session. + **`sessionmode` is evaluated on every request**, not just at session creation. The mode is re-parsed from the auth string each time. If you omit `sessionmode-norotate` on a subsequent request, the session silently falls back to **strict** mode and may rotate on failure. Always use consistent auth strings for all requests within a session. ### Session-Breaking Parameters From 792643d4b36d4296a0010646cccfad077b780e61 Mon Sep 17 00:00:00 2001 From: Valentyn Naboka Date: Tue, 17 Mar 2026 16:55:12 +0100 Subject: [PATCH 3/6] docs: fix norotate accuracy and reduce redundancy Correct remaining discrepancies between code and docs: TTL expiry creates a new session (not 503), rate-limit exceeded replaces the session, and node-gone is the only case that returns 503. Remove duplicate warnings, redundant bullet points, and the second curl example to keep the docs concise. --- .../how-do-i-implement-sticky-sessions.mdx | 4 ++-- .../when-do-sticky-sessions-change-nodes.mdx | 2 +- residential/sticky-sessions.mdx | 22 +++++-------------- 3 files changed, 8 insertions(+), 20 deletions(-) diff --git a/kb/technical/how-do-i-implement-sticky-sessions.mdx b/kb/technical/how-do-i-implement-sticky-sessions.mdx index 077b4e8..88ebb94 100644 --- a/kb/technical/how-do-i-implement-sticky-sessions.mdx +++ b/kb/technical/how-do-i-implement-sticky-sessions.mdx @@ -23,10 +23,10 @@ Parameters Explained: - sessionmode-flex: Flexible session mode (also supports `strict` and `norotate`) - Port 65535: HTTPS (Use 65534 for HTTP, 65533 for SOCKS5) -No-Rotate Example (fails with 502 instead of rotating): +No-Rotate Example (returns 502/503 on node errors instead of rotating): ```bash curl -x https://network.joinmassive.com:65535 \ -U '{USERNAME}-session-37-sessionttl-30-sessionmode-norotate:{PASSWORD}' \ https://cloudflare.com/cdn-cgi/trace -``` \ No newline at end of file +``` diff --git a/kb/technical/when-do-sticky-sessions-change-nodes.mdx b/kb/technical/when-do-sticky-sessions-change-nodes.mdx index b92e7a0..87bf0c2 100644 --- a/kb/technical/when-do-sticky-sessions-change-nodes.mdx +++ b/kb/technical/when-do-sticky-sessions-change-nodes.mdx @@ -10,4 +10,4 @@ Sessions may change under these conditions: 4. Mode-specific conditions: - Flex Mode: After 15 consecutive errors - Strict Mode: Immediate change on failure - - No-Rotate Mode: Never changes nodes — returns 502 (tunnel error) or 503 (node unavailable) instead \ No newline at end of file + - No-Rotate Mode: Returns 502/503 instead of rotating (TTL expiry and rate limits still rotate) diff --git a/residential/sticky-sessions.mdx b/residential/sticky-sessions.mdx index 8c54ad9..186d773 100644 --- a/residential/sticky-sessions.mdx +++ b/residential/sticky-sessions.mdx @@ -39,7 +39,7 @@ When a session identifier is specified and found, the server will perform a requ * The node has gone offline * Error limit is reached (in flex mode) -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 a new node. In **norotate** mode, no new session is created — the request fails with a **502** or **503** error instead. +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 a new node. In **norotate** mode, the request fails instead of rotating (see [No-Rotate Mode](#no-rotate-mode) below). ## Session Modes @@ -89,12 +89,10 @@ curl -x https://network.joinmassive.com:65535 \ ### No-Rotate Mode -Sessions can operate in **norotate mode** where sessions are never rotated to a new node. If the assigned node becomes unavailable or any error occurs, the request fails instead of rotating to a new node. This is useful when IP consistency is critical and you would rather fail than silently switch IPs. +Sessions can operate in **norotate mode** where node errors cause immediate failure instead of rotation. This is useful when IP consistency is critical and you would rather fail than silently switch IPs. Note that TTL expiry and rate-limit exceeded still create a new session (same as other modes). -- Sessions never rotate to a new node -- Returns **502** on tunnel errors (node responds with an error) or **503** when the node is unavailable (gone offline or session expired) +- Returns **502** on tunnel errors (node responds with an error) or **503** when the node has gone offline - The `sessionerr` parameter is ignored in norotate mode — any error fails immediately -- Guarantees that a given session ID always maps to the same node or fails **Consistent auth strings required:** Session parameters (including `sessionmode`) are re-parsed from the auth string on every request. If you omit `sessionmode-norotate` on a subsequent request using the same session ID, the session silently falls back to **strict** mode and may rotate to a new node on failure. Always include `sessionmode-norotate` in every request for the session. @@ -108,14 +106,6 @@ curl -x https://network.joinmassive.com:65535 \ https://cloudflare.com/cdn-cgi/trace ``` -Example combining norotate with a custom TTL: - -```bash -curl -x https://network.joinmassive.com:65535 \ - -U '{PROXY_USERNAME}-session-123-sessionmode-norotate-sessionttl-60:{API_KEY}' \ - https://cloudflare.com/cdn-cgi/trace -``` - ## Additional Parameters | Key | Value | Description | Default | @@ -137,7 +127,7 @@ This example allows up to 5 consecutive errors before rotating to a new node. ## Best Practices 1. **Plan TTL appropriately**: Since sessions use static TTL (not extended by activity), set an appropriate duration for your use case -2. **Choose the right mode**: Default strict mode ensures immediate rotation on any error; use flex mode if you need IP stability; use norotate mode if you need guaranteed IP consistency and prefer failures over silent rotation +2. **Choose the right mode**: Default strict mode ensures immediate rotation on any error; use flex mode if you need IP stability; use norotate mode if you need IP consistency on node errors (TTL expiry and rate limits still rotate) 3. **Monitor error rates**: Adjust `sessionerr` based on your tolerance for retries (default is 15) 4. **Session ID naming**: Use descriptive session IDs to help with debugging and monitoring @@ -154,9 +144,7 @@ This example allows up to 5 consecutive errors before rotating to a new node. ### Parameters Re-parsed on Every Request - - **`sessionmode` is evaluated on every request**, not just at session creation. The mode is re-parsed from the auth string each time. If you omit `sessionmode-norotate` on a subsequent request, the session silently falls back to **strict** mode and may rotate on failure. Always use consistent auth strings for all requests within a session. - + `sessionmode` is evaluated on every request, not just at session creation (see the [norotate warning](#no-rotate-mode) above). ### Session-Breaking Parameters From b91619a8baef5e0b0d99fee19fc2e7e4bda26ad2 Mon Sep 17 00:00:00 2001 From: Valentyn Naboka Date: Wed, 18 Mar 2026 14:22:36 +0100 Subject: [PATCH 4/6] docs: fix norotate accuracy and reduce redundancy --- kb/technical/how-do-i-implement-sticky-sessions.mdx | 10 +--------- kb/technical/when-do-sticky-sessions-change-nodes.mdx | 2 +- residential/sticky-sessions.mdx | 9 ++++----- 3 files changed, 6 insertions(+), 15 deletions(-) diff --git a/kb/technical/how-do-i-implement-sticky-sessions.mdx b/kb/technical/how-do-i-implement-sticky-sessions.mdx index 88ebb94..daace77 100644 --- a/kb/technical/how-do-i-implement-sticky-sessions.mdx +++ b/kb/technical/how-do-i-implement-sticky-sessions.mdx @@ -20,13 +20,5 @@ Parameters Explained: - session-37: Unique session identifier - sessionttl-30: 30-minute session duration -- sessionmode-flex: Flexible session mode (also supports `strict` and `norotate`) +- sessionmode-flex: Flexible session mode - Port 65535: HTTPS (Use 65534 for HTTP, 65533 for SOCKS5) - -No-Rotate Example (returns 502/503 on node errors instead of rotating): - -```bash -curl -x https://network.joinmassive.com:65535 \ --U '{USERNAME}-session-37-sessionttl-30-sessionmode-norotate:{PASSWORD}' \ -https://cloudflare.com/cdn-cgi/trace -``` diff --git a/kb/technical/when-do-sticky-sessions-change-nodes.mdx b/kb/technical/when-do-sticky-sessions-change-nodes.mdx index 87bf0c2..11ae769 100644 --- a/kb/technical/when-do-sticky-sessions-change-nodes.mdx +++ b/kb/technical/when-do-sticky-sessions-change-nodes.mdx @@ -10,4 +10,4 @@ Sessions may change under these conditions: 4. Mode-specific conditions: - Flex Mode: After 15 consecutive errors - Strict Mode: Immediate change on failure - - No-Rotate Mode: Returns 502/503 instead of rotating (TTL expiry and rate limits still rotate) + - No-Rotate Mode: The node does not change until TTL expires diff --git a/residential/sticky-sessions.mdx b/residential/sticky-sessions.mdx index 186d773..8b43e36 100644 --- a/residential/sticky-sessions.mdx +++ b/residential/sticky-sessions.mdx @@ -35,11 +35,10 @@ curl -x https://network.joinmassive.com:65535 \ When a session identifier is specified and found, the server will perform a request via the same node unless: * TTL is expired (sessions expire exactly at creation time + TTL) -* The request limit per minute for the node is exceeded -* The node has gone offline +* The node has gone offline (except in norotate mode) * Error limit is reached (in flex mode) -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 a new node. In **norotate** mode, the request fails instead of rotating (see [No-Rotate Mode](#no-rotate-mode) below). +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 a new node. ## Session Modes @@ -89,7 +88,7 @@ curl -x https://network.joinmassive.com:65535 \ ### No-Rotate Mode -Sessions can operate in **norotate mode** where node errors cause immediate failure instead of rotation. This is useful when IP consistency is critical and you would rather fail than silently switch IPs. Note that TTL expiry and rate-limit exceeded still create a new session (same as other modes). +Sessions can operate in **norotate mode** where node errors cause immediate failure instead of rotation. This is useful when IP consistency is critical and you would rather fail than silently switch IPs. Note that TTL expiry still creates a new session (same as other modes). - Returns **502** on tunnel errors (node responds with an error) or **503** when the node has gone offline - The `sessionerr` parameter is ignored in norotate mode — any error fails immediately @@ -127,7 +126,7 @@ This example allows up to 5 consecutive errors before rotating to a new node. ## Best Practices 1. **Plan TTL appropriately**: Since sessions use static TTL (not extended by activity), set an appropriate duration for your use case -2. **Choose the right mode**: Default strict mode ensures immediate rotation on any error; use flex mode if you need IP stability; use norotate mode if you need IP consistency on node errors (TTL expiry and rate limits still rotate) +2. **Choose the right mode**: Default strict mode ensures immediate rotation on any error; use flex mode if you need IP stability; use norotate mode if you need IP consistency on node errors (TTL expiry still rotates) 3. **Monitor error rates**: Adjust `sessionerr` based on your tolerance for retries (default is 15) 4. **Session ID naming**: Use descriptive session IDs to help with debugging and monitoring From abe9830f971e8731a66e3273efb21486e3bfbc84 Mon Sep 17 00:00:00 2001 From: Valentyn Naboka Date: Wed, 18 Mar 2026 16:18:45 +0100 Subject: [PATCH 5/6] Apply suggestion from @valentin-naboka Signed-off-by: Valentyn Naboka --- residential/sticky-sessions.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/residential/sticky-sessions.mdx b/residential/sticky-sessions.mdx index 8b43e36..5ae4630 100644 --- a/residential/sticky-sessions.mdx +++ b/residential/sticky-sessions.mdx @@ -35,6 +35,7 @@ curl -x https://network.joinmassive.com:65535 \ When a session identifier is specified and found, the server will perform a request via the same node unless: * TTL is expired (sessions expire exactly at creation time + TTL) + * The request limit per minute for the node is exceeded (only for strict mode) * The node has gone offline (except in norotate mode) * Error limit is reached (in flex mode) From e860c3fc5d292705f0b19d67fe86e023fa18c8a1 Mon Sep 17 00:00:00 2001 From: Valentyn Naboka Date: Wed, 18 Mar 2026 16:19:11 +0100 Subject: [PATCH 6/6] Apply suggestion from @valentin-naboka Signed-off-by: Valentyn Naboka --- residential/sticky-sessions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/residential/sticky-sessions.mdx b/residential/sticky-sessions.mdx index 5ae4630..1f1ce4a 100644 --- a/residential/sticky-sessions.mdx +++ b/residential/sticky-sessions.mdx @@ -35,7 +35,7 @@ curl -x https://network.joinmassive.com:65535 \ When a session identifier is specified and found, the server will perform a request via the same node unless: * TTL is expired (sessions expire exactly at creation time + TTL) - * The request limit per minute for the node is exceeded (only for strict mode) +* The request limit per minute for the node is exceeded (only for strict mode) * The node has gone offline (except in norotate mode) * Error limit is reached (in flex mode)