Skip to main content
These features are only available for HTTP type API Proxies. These settings are not valid for gRPC and WebSocket type API Proxies.

​
What is Sticky Session?

Sticky Session is a mechanism that ensures the same client is always routed to the same backend. This can be used in scenarios such as session state, cache locality, or backend-specific data consistency.

​
Use Cases

  • Session State: If session state is maintained in the backend, the same client must always be routed to the same backend
  • Cache Locality: If there is client-specific cache in the backend, sticky session can be used to increase cache hit rate
  • Backend-Specific Data: If backend-specific data is maintained for the client, sticky session may be required for consistency

​
Sticky Session Types

Apinizer supports three different sticky session types:
TypeDescription
COOKIE_ONLYOnly cookie is used. If cookie is missing or invalid, IP hash fallback is performed.
IP_HASHOnly consistent hash based on client IP is used. Cookie is not used.
HYBRIDCookie is checked first, if missing or invalid, IP hash is used.

​
Sticky Session Flow

The sticky session mechanism works as follows:
  1. When a request arrives, the sticky session type is checked:
    • IP_HASH: Backend is selected directly by IP hash and request is sent (cookie is not set)
    • COOKIE_ONLY or HYBRID: Cookie check is performed
  2. Cookie check (for COOKIE_ONLY or HYBRID):
    • If cookie is missing or invalid: Backend is selected by IP hash and cookie is set
    • If cookie exists: Cookie is read and validated
  3. After cookie validation:
    • If backend address in cookie is not in current backend list: Warning is logged, new backend is selected by IP hash, and cookie is updated
    • If circuit breaker status of backend in cookie is OPEN: Warning is logged, new backend is selected by IP hash, and cookie is updated
    • If backend in cookie is valid and healthy: Backend from cookie is used
  4. After backend selection is complete:
    • If sticky type is not IP_HASH: Cookie is set
    • Request is sent to selected backend
Cookie-based sticky session uses secure cookies signed with HMAC-SHA256. The cookie format is as follows: 
Cookie: sticky-session-name=base64(backendAddress:signature)
  • backendAddress: Backend URL address
  • signature: Signature calculated with HMAC-SHA256
  • Encoding: Base64 URL-safe encoding (no padding)
Cookie validation process:
  1. Cookie Reading: Cookie value is read from request header
  2. Base64 Decode: Cookie value is decoded
  3. Signature Verification: Signature is verified with HMAC-SHA256
  4. Backend Address Extraction: Backend address is extracted from valid cookie
If cookie signature validation fails, the cookie is considered invalid and IP hash fallback is performed. This prevents cookie manipulation attacks.
Cookie is added to response header using the response header management mechanism:
Thanks to the response header management mechanism, multiple cookies (e.g., PolicyOIDC and StickySession) can be added to the response simultaneously. Existing cookies are preserved.
ParameterDescription
Sticky Cookie NameName of the cookie. No default value, must be specified.
Sticky Cookie TTLCookie validity duration (seconds). If not specified, becomes a session cookie.
Sticky Cookie HttpOnlyWhether the cookie can be accessed from JavaScript.
Sticky Cookie SecureWhether the cookie is sent only over HTTPS.
Sticky Hash SecretSecret key used for HMAC-SHA256 signature. If not specified, default value is used.

​
Backend Availability and Circuit Breaker

Sticky session checks backend availability and circuit breaker status.

​
Backend Availability Check

If the backend address in the cookie is not in the current backend list:
  1. Warning Logged: Warning that backend is no longer available
  2. IP Hash Fallback: New backend is selected by IP hash
  3. Cookie Updated: New backend address is written to cookie

​
Circuit Breaker Integration

The circuit breaker status of the backend in the cookie is checked:
  • Circuit CLOSED: Backend is healthy, backend from cookie is used
  • Circuit OPEN: Backend is unhealthy, new backend is selected and cookie is updated
Circuit breaker check is performed after cookie validation and backend availability check. This ensures that requests are not sent to unhealthy backends.

​
IP Hash Fallback

If cookie is missing, invalid, or backend is not available, backend is selected by IP hash.

​
Consistent Hashing

IP hash performs consistent hashing based on client IP:
  1. IP Hash Calculation: Math.abs(clientIp.hashCode())
  2. Backend Selection: hash % backends.size()
  3. Consistency: Same IP always routes to the same backend
IP hash selects the same backend as long as the client IP does not change. This provides sticky session-like behavior without cookies.

​
Sticky Session and Load Balancing

Sticky session can be used together with load balancing algorithms:
  • Initial Request: Backend is selected with load balancing algorithm (Round Robin, Weighted, LRU, Random)
  • Subsequent Requests: Backend from cookie is used (after availability and circuit breaker checks)
When sticky session is active, load balancing is only valid for the initial request. Subsequent requests are routed to the backend in the cookie.