Session-Based Sticky Load Balancing for Spring Cloud Gateway

[Gebreyesus]

Summary for the Spring Cloud Gateway proposal

The gap worth raising upstream: Spring Cloud Gateway's default load-balancer filter doesn't pass enough per-request context (or provide a per-route hook) for a custom ReactorServiceInstanceLoadBalancer to implement session-based sticky routing, forcing consumers to fully replace the default filter just to get access to the ServerWebExchange/session on a per-route basis. The built-in RequestBasedStickySessionServiceInstanceListSupplier solves a similar problem but only for cookie-based affinity applied uniformly to a service, not for gateway-session-based affinity that can be toggled per route.

A useful ask for the issue: expose a supported extension point (or request context type) in the default gateway load-balancer filter that lets a custom ReactorServiceInstanceLoadBalancer access the ServerWebExchange/session per-route, without requiring downstream consumers to disable and reimplement the entire filter. Prior related discussion: spring-cloud/spring-cloud-commons#764 and #1176.

[spencergibb]

How is this different than #1176?

[Gebreyesus]

@spencergibb Good question, and the short answer is: partly the same gap, but with a specific difference in the affinity storage mechanism that request-based-sticky-session doesn't address.

What #1176 / spring-cloud-commons#689 delivered: RequestBasedStickySessionServiceInstanceListSupplier with spring.cloud.loadbalancer.configurations: request-based-sticky-session works well when clients can store and echo a cookie containing the instance ID. That's the right solution for most cases, and as tengcomplex demonstrated last month in #1176, it's composable with a custom response filter in SCG to avoid touching the downstream service.

The specific gap this PR addresses: Our production constraint is related to a legacy monolithic application that cannot support distributed sessions. In that scenario, we cannot ask the client to manage a sticky-session cookie, because:

1. The client is a browser running the monolith's own session — the sticky affinity needs to be stored server-side in the gateway's WebSession, not in a client cookie that could be absent, cleared, or tampered with.
2. request-based-sticky-session is configured per service, not per route. When one gateway routes to both a stateful legacy service and stateless microservices on different routes for the same service ID, there is no supported way to make only the legacy-service routes sticky while leaving the others on round-robin.

What the PR does differently:

• Affinity is stored server-side in the gateway WebSession — the client sends no cookie and needs no awareness of instance IDs.
• Opt-in is per-route via the sticky:// URI scheme, so lb:// routes to the same service remain unaffected.
• The implementation surfaces the underlying gap in ReactiveLoadBalancerClientFilter: because it passes RequestDataContext rather than the ServerWebExchange, a custom ReactorServiceInstanceLoadBalancer cannot access the gateway session without replacing the filter entirely. The PR works around this by adding a parallel filter that passes the exchange as context.

If the preferred direction is an extension point inside ReactiveLoadBalancerClientFilter (e.g. making createRequest() protected and overridable, as suggested in #1176 by @Fetsivalen in 2020) rather than a parallel filter, I'm happy to revise the approach. The implementation in PR #4234 can be reframed as a GatewayFilterFactory that sets a session-affinity flag on the exchange and delegates to the existing filter, which would be more composable and idiomatic.