Sticky Sessions / Session Affinity

[abdallahsamabd]

Problem

Today Praxis supports session affinity only through stateless consistent hashing — a request header value (or URI path) is hashed to select an endpoint. This works for clients that can send a stable identifier header, but it has significant limitations:

1. No cookie-based persistence — browsers and HTTP clients that rely on cookies for session tracking cannot benefit from proxy-level affinity without application-level workarounds.
2. No proxy-managed session cookie — there is no mechanism for Praxis to inject a session cookie into responses that pins the client to a specific backend.
3. No learn mode — Praxis cannot extract session identifiers from upstream responses (e.g., JSESSIONID from a Tomcat backend) to build a mapping.
4. No shared session table — consistent hashing is stateless per-request; there is no cross-worker session-to-endpoint mapping, so endpoint changes cause silent re-routing.
5. No graceful failover — when a pinned backend becomes unhealthy, there is no automatic re-pin to a healthy endpoint with session table update.
6. No cookie attribute control — operators cannot configure HttpOnly, Secure, SameSite, Path, Domain, or Max-Age for session cookies.

These gaps prevent Praxis from supporting stateful applications (shopping carts, server-side sessions, multi-turn AI inference, chunked uploads) that require true session persistence.

Issue: #108
Epic: #163 (Resilience and Traffic Management)
Proposal PR: #904
Proposal(how ): #922

Proposal

Add cookie-based and header-based session persistence to pin clients to specific upstream endpoints across requests. The feature includes:

• Cookie-based persistence: Praxis sets a session cookie mapping the client to a specific endpoint. On subsequent requests, Praxis reads this cookie and routes directly (skipping load balancer selection).
• Cookie attributes: Full control over domain, path, expires/max-age, httponly, secure, samesite.
• Header-based persistence: Use a request header value (e.g., X-Session-Id) to select and pin to an endpoint, with a server-side mapping (beyond today's stateless hashing).
• Learn mode: Extract the session identifier from an upstream response header (e.g., Set-Cookie: JSESSIONID=abc123) and automatically build the session-to-endpoint mapping.
• Shared session-to-endpoint mapping: Thread-safe, cross-worker data structure so all proxy workers agree on which session maps to which endpoint.
• Graceful failover: When a pinned endpoint fails health checks, automatically re-pin the session to a healthy endpoint and update the mapping.
• Load balancer integration: Session affinity overrides normal LB selection — LB only runs on the first request of a session (cache miss); subsequent requests route directly via the session map.

Example configuration

clusters:
  - name: app_backend
    endpoints:
      - address: "10.0.1.1:8080"
      - address: "10.0.1.2:8080"
      - address: "10.0.1.3:8080"
    session_persistence:
      type: cookie            # cookie | header | learn
      cookie_name: "_praxis_route"
      ttl_secs: 3600
      cookie_attributes:
        path: "/"
        http_only: true
        secure: true
        same_site: "Lax"
      failover: true          # re-pin on unhealthy endpoint

[shaneutt]

maintainer +1