SSE initial implementation #204

calebbourg · 2025-11-15T16:47:59Z

Description

This PR implements the foundational infrastructure for Server-Sent Events (SSE) to enable real-time, one-way communication from the backend to authenticated users. This establishes the core architecture needed for future real-time features like action notifications, coaching session updates, and system announcements.

GitHub Issue: [Closes|Fixes|Resolves] #your GitHub issue number here

Changes

New sse crate: Standalone crate with generic types (String IDs, JSON payloads) to avoid circular dependencies
- ConnectionRegistry: Dual-index architecture using DashMap for O(1) concurrent lookups by connection_id and user_id
- Manager: High-level API for connection lifecycle and message routing
- Message types: Event enum with action, agreement, goal, and system event variants
- MessageScope: User-targeted and broadcast message delivery
SSE HTTP endpoint (web/src/sse/handler.rs): GET /sse endpoint for establishing long-lived SSE connections
- Async streaming using async_stream::stream! and Tokio channels
- Automatic connection cleanup on disconnect
- One connection per authenticated user, persisting across page navigation
AppState integration: Added sse_manager: Arc<sse::Manager> to service layer's AppState
- Enables controllers to send SSE events via app_state.sse_manager.send_message()
- Manager initialized at application startup in main.rs and seed_db.rs
Infrastructure configuration:
- Nginx configuration for /api/sse endpoint (24h timeout, no buffering, chunked encoding)
- Docker Compose warning about single-instance limitation (in-memory connection tracking)
Testing tool (sse-test-client): CLI tool for integration testing SSE functionality
- Connection stability testing
- Force logout scenario
- Multiple test scenarios with varying permission requirements
Architecture documentation updates: Updated crate dependency graph, system architecture diagram, and network flow diagram
to reflect SSE components

Testing Strategy

Manual testing with sse-test-client:

cd sse-test-client
cargo run
# Select "Connection Test" to verify basic SSE connectivity

Unit tests: Updated auth middleware tests to include SSE manager initialization
Integration testing: Use sse-test-client scenarios to verify:

Connection establishment and stability
Multiple concurrent user connections
Graceful connection cleanup on disconnect

Concerns

Single-instance limitation: SSE connections are tracked in-memory using DashMap, which means the application cannot scale horizontally without implementing Redis Pub/Sub for cross-instance event distribution
- Warning added to docker-compose.yaml
- Symptom if violated: events randomly fail to deliver with multiple replicas
No event persistence: All SSE events are ephemeral - offline users miss events and see fresh data on next page load
No message delivery guarantees: If channel send fails, events are dropped (logged but not retried)
Generic types in SSE crate: Using String for IDs and serde_json::Value for payloads to avoid circular dependencies - type safety enforced at web layer boundaries

better connection lookup and remove the need for unwrap

- Add critical warning to docker-compose.yaml about SSE single-instance limitation * SSE connections tracked in-memory with DashMap * Must not scale horizontally without Redis Pub/Sub * Warns about symptom: events randomly fail with multiple replicas - Add nginx configuration for /api/sse endpoint * Disable proxy buffering for immediate event streaming * Set 24h read timeout for long-lived SSE connections * Enable chunked transfer encoding * Clear connection header for proper streaming * Add CORS headers for credential support 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Create standalone SSE crate to avoid circular dependencies between service and web layers. Uses generic types (String for IDs, serde_json::Value for payloads) to remain independent of domain models. Key components: - ConnectionRegistry: Dual-index (connection_id, user_id) architecture using DashMap for O(1) concurrent lookups - Manager: High-level API for connection lifecycle and message routing - Message types: Event enum with action, agreement, goal, and system events - MessageScope: User-targeted and broadcast message delivery Architecture decisions: - In-memory connection tracking (single-instance only) - Generic types to avoid domain dependency - Thread-safe using DashMap and Arc - Tokio channels for event distribution 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Add SSE manager to the service layer's AppState to enable real-time event distribution throughout the application. The manager is wrapped in Arc for thread-safe sharing across request handlers. Changes: - Add sse dependency to service crate - Add sse_manager: Arc<sse::Manager> field to AppState - Update AppState::new() to accept sse_manager parameter - Make sse_manager publicly accessible via getter This allows controllers to send SSE events by calling app_state.sse_manager.send_message() with appropriate message scope. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Implement Axum SSE handler that establishes long-lived HTTP connections for server-sent events. One connection per authenticated user, persisting across page navigation. Implementation: - Handler at GET /sse (behind authentication middleware) - Uses async_stream::stream! for event streaming - Registers user connection with SSE manager - Automatic cleanup when connection closes - Returns Sse<impl Stream<Item = Result<Event, Infallible>>> - Keep-alive enabled with default settings Technical details: - Tokio unbounded channel receives events from manager - Stream yields events as they arrive from channel - Connection ID generated server-side for lifecycle tracking - Converts domain::Id to String for SSE layer compatibility 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Create and pass SSE manager instance to AppState in both the main application and database seeding utility. Changes: - main.rs: Initialize Arc<sse::Manager::new()> and pass to AppState - seed_db.rs: Initialize SSE manager for test data seeding context The manager is created once at startup and shared across all request handlers via Arc for thread-safe access. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Update three authentication middleware tests to initialize SSE manager when creating AppState, matching the new 3-parameter constructor signature. Fixed tests: - test_require_auth_returns_401_with_no_session - test_require_auth_returns_401_with_invalid_session_cookie - test_require_auth_allows_authenticated_request_to_proceed Each test now creates Arc<sse::Manager::new()> before constructing AppState to maintain test isolation while matching production code. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Update project documentation to reflect the new SSE (Server-Sent Events) real-time communication infrastructure. Changes: - README.md: Add sse crate to project directory structure - crate_dependency_graph.md: Add sse crate dependencies (web→sse, service→sse) - system_architecture_diagram.md: Add SSE Handler and SSE Manager components with event flow from domain layer - network_flow_diagram.md: Document SSE endpoint configuration and single-instance scaling limitation Key documentation notes: - SSE uses in-memory connection tracking (single-instance only) - Nginx configured for long-lived connections (24h timeout, no buffering) - Generic types used in sse crate to avoid circular dependencies 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

…ling - Change login endpoint from /user_sessions to /login - Use form-encoded data instead of JSON for login requests - Update cookie name from session_id to id throughout codebase - Parse ApiResponse wrapper structure for user data - Improve error messages with response body details 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

- Add x-version: 1.0.0-beta1 header to all API requests - Fix coaching relationships endpoint to include organization_id - Add get_user_organizations method to fetch user's orgs - Parse ApiResponse wrapper for all endpoint responses - Update all cookie headers to use 'id' instead of 'session_id' 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Add test_connection function that verifies basic SSE connectivity without requiring coaching data. This scenario: - Establishes SSE connections for both users - Waits 2 seconds to verify connections stay alive - Reports success if connections remain stable This allows testing SSE infrastructure without admin permissions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

- Add ConnectionTest scenario choice to CLI - Add ForceLogoutTest scenario choice to CLI - Make test environment setup conditional (skip for ConnectionTest) - Update All scenario to include ConnectionTest - Improve scenario descriptions with requirements ConnectionTest can run without admin permissions since it doesn't require creating coaching relationships or sessions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

…rceLogoutTest - Remove unused test_env parameter from test_force_logout function - Skip test environment setup for ForceLogoutTest scenario - Fix force_logout cookie header to use 'id' instead of 'session_id' - Update README with new connection-test scenario documentation - Clarify permission requirements for each test scenario - Add example output for connection test 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

jhodapp · 2025-12-05T14:46:41Z

@calebbourg I don't seem to be able to run the sse-test-client successfully on my local machine, I might be missing something but I am running with the examples provided under sse-test-client/README.md.

Here's what I'm getting:

> cargo run -p sse-test-client -- \
  --base-url http://localhost:4000 \
  --user1 "user1@example.com:password123" \
  --user2 "user2@example.com:password456" \
  --scenario connection-test

=== SETUP PHASE ===
→ Authenticating users...
Error: Login failed: 401 Unauthorized - Response: UNAUTHORIZED

I'm guessing that I need to use a real test user from our seeded data for dev. If this is what I'm missing, I recommend updating the documentation in this README.md to just use the actual users instead of non-existent ones since this data isn't for production anyway and poses no security threat.

jhodapp · 2025-12-05T14:51:35Z

sse-test-client/README.md

+  --user1 "user1@example.com:password123" \
+  --user2 "user2@example.com:password456" \


Let's use the real seeded dev data here since it poses no security threat and helps a developer trying to use these examples to already have them ready to copy + paste from here.

jhodapp · 2025-12-05T14:53:30Z

sse-test-client/src/main.rs

+
+    /// User 1 credentials (format: email:password)
+    #[arg(long)]
+    user1: String,


For this test client, do we always need to test with a coach and a coachee?

jhodapp · 2025-12-05T14:55:44Z

Now I'm seeing the following error once I use two valid users (me as a user, and you as a user) when running the sse-test-client:

> cargo run -p sse-test-client -- \
  --base-url http://localhost:4000 \
  --user1 "jim@refactorcoach.com:password" \
  --user2 "calebbourg2@gmail.com:password" \
  --scenario action-create

14:49:39 [INFO] summary="SELECT DISTINCT \"organizations\".\"id\", \"organizations\".\"name\", …" db.statement="\n\nSELECT DISTINCT \"organizations\".\"id\", \"organizations\".\"name\", \"organizations\".\"logo\", \"organizations\".\"slug\", \"organizations\".\"created_at\", \"organizations\".\"updated_at\" FROM \"refactor_platform\".\"organizations\" INNER JOIN \"refactor_platform\".\"user_roles\" ON \"organizations\".\"id\" = \"user_roles\".\"organization_id\" WHERE \"user_roles\".\"user_id\" = $1\n" rows_affected=1 rows_returned=1 elapsed=224.417µs elapsed_secs=0.000224417
14:49:39 [DEBUG] (2) sea_orm::driver::sqlx_postgres: SELECT "coaching_relationships"."id", "coaching_relationships"."organization_id", "coaching_relationships"."coach_id", "coaching_relationships"."coachee_id", "coaching_relationships"."slug", "coaching_relationships"."created_at", "coaching_relationships"."updated_at" FROM "refactor_platform"."coaching_relationships" WHERE "coaching_relationships"."organization_id" IN (SELECT "organizations"."id" FROM "refactor_platform"."organizations" WHERE "organizations"."id" = '7254d83b-75bb-4523-89e6-7c17005c4a7e')
14:49:39 [INFO] summary="SELECT \"coaching_relationships\".\"id\", \"coaching_relationships\".\"organization_id\", \"coaching_relationships\".\"coach_id\", …" db.statement="\n\nSELECT \"coaching_relationships\".\"id\", \"coaching_relationships\".\"organization_id\", \"coaching_relationships\".\"coach_id\", \"coaching_relationships\".\"coachee_id\", \"coaching_relationships\".\"slug\", \"coaching_relationships\".\"created_at\", \"coaching_relationships\".\"updated_at\" FROM \"refactor_platform\".\"coaching_relationships\" WHERE \"coaching_relationships\".\"organization_id\" IN (SELECT \"organizations\".\"id\" FROM \"refactor_platform\".\"organizations\" WHERE \"organizations\".\"id\" = $1)\n" rows_affected=5 rows_returned=5 elapsed=2.769666ms elapsed_secs=0.002769666
14:49:39 [ERROR] Coaching relationship already exists for coach: a37817a8-ad03-4f04-a6a4-2fe9ca070172 and coachee: 9b66b36a-62f3-4815-a6bb-0a62756537c2 in organization: 00000000-0000-0000-0000-000000000000
14:49:39 [WARN] EntityErrorKind::Other: Responding with 500 Internal Server Error. Error: Domain(Error { source: Some(Error { source: None, error_kind: ValidationError }), error_kind: Internal(Entity(Other("EntityErrorKind"))) })

jhodapp · 2025-12-05T16:16:35Z

sse-test-client/src/api_client.rs

@calebbourg As we discussed in our sync, consider moving sse-test-client into something like a tools directory or test-tools or something like it.

calebbourg · 2025-12-05T16:31:12Z

nginx/conf.d/refactor-platform.conf

        add_header Content-Type text/plain;
    }

+    # SSE endpoint requires special configuration to prevent nginx from


Can we add monitoring to this somehow in DO?

calebbourg and others added 15 commits November 15, 2025 11:20

update sse plan

1b30d93

better connection lookup and remove the need for unwrap

add integration testing tool design to sse plan

cda0f75

add sse-test-client initial implementation

18cafcc

calebbourg marked this pull request as ready for review December 1, 2025 14:24

calebbourg self-assigned this Dec 1, 2025

calebbourg requested a review from jhodapp December 1, 2025 14:25

cargo fmt

25ffb54

jhodapp changed the title ~~Sse initial implementation~~ SSE initial implementation Dec 5, 2025

jhodapp added the feature work Specifically implementing a new feature label Dec 5, 2025

jhodapp added this to Refactor Coaching Platform Dec 5, 2025

jhodapp moved this to Review in Refactor Coaching Platform Dec 5, 2025

jhodapp added this to the 1.0.0-beta2 milestone Dec 5, 2025

jhodapp reviewed Dec 5, 2025

View reviewed changes

calebbourg commented Dec 5, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

SSE initial implementation #204

SSE initial implementation #204

Uh oh!

calebbourg commented Nov 15, 2025 •

edited by jhodapp

Loading

Uh oh!

jhodapp commented Dec 5, 2025 •

edited

Loading

Uh oh!

jhodapp Dec 5, 2025

Uh oh!

jhodapp Dec 5, 2025

Uh oh!

jhodapp commented Dec 5, 2025 •

edited

Loading

Uh oh!

jhodapp Dec 5, 2025

Uh oh!

calebbourg Dec 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		--user1 "user1@example.com:password123" \
		--user2 "user2@example.com:password456" \

SSE initial implementation #204

Are you sure you want to change the base?

SSE initial implementation #204

Uh oh!

Conversation

calebbourg commented Nov 15, 2025 • edited by jhodapp Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

GitHub Issue: [Closes|Fixes|Resolves] #your GitHub issue number here

Changes

Testing Strategy

Concerns

Uh oh!

jhodapp commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jhodapp Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

jhodapp Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

jhodapp commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jhodapp Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

calebbourg Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

calebbourg commented Nov 15, 2025 •

edited by jhodapp

Loading

jhodapp commented Dec 5, 2025 •

edited

Loading

jhodapp commented Dec 5, 2025 •

edited

Loading