feat(mentor): Traefik sticky cookies for replica affinity

Pin user/workspace traffic to the replica holding the in-JVM
PiProcessHandle so SSE turns don't pay a sandbox cold-start each
reconnect. Also stamp every response with X-Hephaestus-Replica so
the affinity is observable from curl or DevTools.

- Traefik labels on https-application-server: sticky cookie
  __Secure-hep_workspace_aff, Path=/api/workspaces (matches the
  actual mentor URL /api/workspaces/{slug}/mentor/chat), maxAge=300
  aligned with hephaestus.mentor.idle-ttl-seconds. Healthcheck
  labels so Traefik rewrites the affinity cookie on replica death.
- Bump Traefik v3.2 -> v3.4: sticky.cookie.path landed in v3.3
  (PR traefik/traefik#11166), the label is silently dropped on
  v3.2.
- ReplicaIdentityFilter (OncePerRequestFilter, HIGHEST_PRECEDENCE)
  emits X-Hephaestus-Replica from $HOSTNAME with InetAddress
  fallback for non-Docker dev. CORS exposes the header via the
  same constant so SecurityConfig and the filter can't drift.
- Preview compose is single-replica by design and intentionally
  omits the labels.
- Contributor doc at docs/contributor/unified-pi-runtime.mdx
  covers the affinity, known limitations, and how to disable.

Fixes #1077

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: FelixTJDietrich

docker/compose.app.yaml

@@ -166,6 +166,18 @@ services:
       - "traefik.http.services.https-application-server.loadbalancer.server.port=8080"
       - "traefik.http.routers.http-application-server.priority=5"
       - "traefik.http.routers.https-application-server.priority=10"
+      # Replica affinity for workspace traffic (mentor lives here) — see docs/contributor/unified-pi-runtime.mdx.
+      # maxAge=300 matches hephaestus.mentor.idle-ttl-seconds; cookie.path requires Traefik >=3.3.
+      - "traefik.http.services.https-application-server.loadbalancer.sticky.cookie=true"
+      - "traefik.http.services.https-application-server.loadbalancer.sticky.cookie.name=__Secure-hep_workspace_aff"
+      - "traefik.http.services.https-application-server.loadbalancer.sticky.cookie.httpOnly=true"
+      - "traefik.http.services.https-application-server.loadbalancer.sticky.cookie.secure=true"
+      - "traefik.http.services.https-application-server.loadbalancer.sticky.cookie.sameSite=lax"
+      - "traefik.http.services.https-application-server.loadbalancer.sticky.cookie.path=/api/workspaces"
+      - "traefik.http.services.https-application-server.loadbalancer.sticky.cookie.maxAge=300"
+      - "traefik.http.services.https-application-server.loadbalancer.healthcheck.path=/actuator/health/liveness"
+      - "traefik.http.services.https-application-server.loadbalancer.healthcheck.interval=10s"
+      - "traefik.http.services.https-application-server.loadbalancer.healthcheck.timeout=3s"
     healthcheck:
       test: "wget -qO- http://localhost:8080/actuator/health || exit 1"
       interval: 5s

docker/compose.proxy.yaml

@@ -1,6 +1,6 @@
 services:
   reverse-proxy:
-    image: traefik:v3.2
+    image: traefik:v3.4
     restart: unless-stopped
     networks:
       - shared-network

docker/preview/compose.app.yaml

@@ -178,6 +178,10 @@ services:
   # Application Server - Spring Boot backend
   # Main app domain (set once): https://api.hephaestus.example.com
   # Previews auto-generate: https://{{pr_id}}.api.hephaestus.example.com
+  #
+  # Replica affinity: previews are single-replica by design, so the mentor sticky-cookie
+  # labels from docker/compose.app.yaml are intentionally omitted here — they would be a
+  # no-op. See docs/contributor/unified-pi-runtime.mdx.
   # ---------------------------------------------------------------------------
   application-server:
     build:

docs/contributor/unified-pi-runtime.mdx

@@ -0,0 +1,26 @@
+---
+id: unified-pi-runtime
+sidebar_position: 3
+title: Unified Pi Runtime
+description: Mentor replica affinity and how to disable it for debugging.
+---
+
+## Why mentor traffic is sticky
+
+The mentor SSE endpoint opens a long-lived `docker exec -i` against the user's Pi container (`PiProcessHandle`). The stdin/stdout pipes live in JVM memory; the conversation itself is persisted to Postgres (`chat_thread.session_jsonl`, BYTEA), so any replica can serve any turn — but a replica without the live pipes must rebuild the sandbox first, paying a cold-start cost tracked by `InteractiveSandboxMetrics.attachDuration`.
+
+Traefik pins workspace traffic to the originating replica via a cookie scoped to `/api/workspaces` — narrower than the full `/api` router (auth and public endpoints stay round-robin), broad enough to cover the actual mentor URL `/api/workspaces/{slug}/mentor/chat`. Labels live on the `https-application-server` service in `docker/compose.app.yaml`. Inspect with `curl -i`:
+
+- Cookie: `__Secure-hep_workspace_aff` — `Secure`, `HttpOnly`, `SameSite=Lax`, `maxAge` matches `hephaestus.mentor.idle-ttl-seconds` (300s default) so the cookie expires when the sandbox is reaped.
+- Response header: `X-Hephaestus-Replica: <container-id-prefix>` — emitted by `ReplicaIdentityFilter` from `$HOSTNAME`, CORS-exposed for the webapp.
+
+Labels are HTTPS-only; the HTTP router redirects to HTTPS, so pinning it would just double-issue cookies. The `cookie.path` attribute requires Traefik >= 3.3 (the proxy is pinned to v3.4 in `docker/compose.proxy.yaml`). Previews (`docker/preview/compose.app.yaml`) are single-replica and omit the labels.
+
+## Known limitations
+
+- **Two browsers, same user.** Two browsers can pin to two replicas, each spawning its own `(userId, workspaceId)` sandbox — `InteractiveSandboxRegistry` is per-JVM.
+- **Rolling deploys.** Each pinned user whose replica restarts pays one cold start. The `SseEmitter` timeout is 10 minutes (`MentorChatController.EMITTER_TIMEOUT_MS`); drain by refusing new turns and letting in-flight emitters complete.
+
+## Disabling affinity for debugging
+
+Delete the `traefik.http.services.https-application-server.loadbalancer.sticky.*` labels from `docker/compose.app.yaml` and redeploy. Existing sessions stay pinned until the cookie expires; new sessions round-robin. Expect transient 5xx on reconnects that land on a cold replica.

docs/sidebars.contributor.ts

@@ -25,7 +25,7 @@ const sidebars: SidebarsConfig = {
     {
       type: 'category',
       label: 'AI Development',
-      items: ['ai-agent-workflow', 'ai-code-review'],
+      items: ['ai-agent-workflow', 'ai-code-review', 'unified-pi-runtime'],
     },
   ],
 };

server/application-server/src/main/java/de/tum/in/www1/hephaestus/SecurityConfig.java

@@ -2,6 +2,7 @@
 
 import de.tum.in.www1.hephaestus.config.CorsProperties;
 import de.tum.in.www1.hephaestus.feature.FeatureFlag;
+import de.tum.in.www1.hephaestus.observability.ReplicaIdentityFilter;
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
@@ -142,6 +143,7 @@ CorsConfigurationSource corsConfigurationSource() {
         configuration.setAllowedHeaders(
             List.of("Authorization", "Content-Type", "Accept", "X-Requested-With", "Origin")
         );
+        configuration.setExposedHeaders(List.of(ReplicaIdentityFilter.HEADER_NAME));
         configuration.setAllowCredentials(true);
         configuration.setMaxAge(3600L);
         UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();

server/application-server/src/main/java/de/tum/in/www1/hephaestus/observability/ReplicaIdentityFilter.java

@@ -0,0 +1,50 @@
+package de.tum.in.www1.hephaestus.observability;
+
+import jakarta.annotation.PostConstruct;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.net.InetAddress;
+import java.net.UnknownHostException;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+/** Stamps every response with the serving replica id — see docs/contributor/unified-pi-runtime.mdx. */
+@Component
+@Order(Ordered.HIGHEST_PRECEDENCE)
+public class ReplicaIdentityFilter extends OncePerRequestFilter {
+
+    public static final String HEADER_NAME = "X-Hephaestus-Replica";
+
+    private static final Logger log = LoggerFactory.getLogger(ReplicaIdentityFilter.class);
+    private static final String REPLICA_ID = resolveReplicaId();
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
+        throws ServletException, IOException {
+        response.setHeader(HEADER_NAME, REPLICA_ID);
+        chain.doFilter(request, response);
+    }
+
+    @PostConstruct
+    void announceReplica() {
+        log.info("Replica id: {}", REPLICA_ID);
+    }
+
+    // HOSTNAME is the container id under Docker; InetAddress fallback is dev-only.
+    private static String resolveReplicaId() {
+        String env = System.getenv("HOSTNAME");
+        if (env != null && !env.isBlank()) return env;
+        try {
+            return InetAddress.getLocalHost().getHostName();
+        } catch (UnknownHostException e) {
+            return "unknown";
+        }
+    }
+}

server/application-server/src/test/java/de/tum/in/www1/hephaestus/observability/ReplicaIdentityFilterTest.java

@@ -0,0 +1,18 @@
+package de.tum.in.www1.hephaestus.observability;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import de.tum.in.www1.hephaestus.testconfig.BaseUnitTest;
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+
+class ReplicaIdentityFilterTest extends BaseUnitTest {
+
+    @Test
+    void setsReplicaHeader() throws Exception {
+        var response = new MockHttpServletResponse();
+        new ReplicaIdentityFilter().doFilter(new MockHttpServletRequest(), response, (req, res) -> {});
+        assertThat(response.getHeader(ReplicaIdentityFilter.HEADER_NAME)).isNotBlank();
+    }
+}