implementation_plan.md

Migrate SSE Implementation to Datastar-Go

Problem Description

The current sse.go implementation uses a custom Server-Sent Events (SSE) broadcaster pattern with manual channel management. The goal is to migrate to the official github.com/starfederation/datastar-go library to leverage its built-in SSE capabilities and integrate better with the datastar.dev frontend framework.

Current Implementation

The existing code has:

• Two custom broadcasters (NotificationBroadcaster and WorkflowBroadcaster)
• Manual SSE header management
• Custom heartbeat implementation
• Channel-based client management with cleanup logic
• Two public functions: BroadcastNotification() and BroadcastWorkflowUpdate()

Proposed Changes

Dependencies

[MODIFY] go.mod

Add the datastar-go dependency to the project.

---

Core SSE Handler Rewrite

[MODIFY] sse.go

Key Changes:

1. Remove custom broadcaster structs: Remove NotificationBroadcaster and WorkflowBroadcaster structs along with their channel-based client management.

2. Use datastar.NewSSE(): Replace manual SSE header setting and flusher logic with datastar.NewSSE(w, r).

3. Simplify StreamNotifications handler:

   • Use datastar.NewSSE() to create the SSE writer
   • Use datastar's built-in methods for sending events
   • Maintain heartbeat logic for keeping connections alive
   • Remove manual header management

4. Simplify StreamWorkflowStatus handler:

   • Similar pattern to StreamNotifications
   • Keep orderID-based filtering
   • Use datastar SSE methods

5. Update broadcast functions:

   • BroadcastNotification(): Store connected SSE writers and send to all
   • BroadcastWorkflowUpdate(): Store per-orderID SSE writers and send to matching clients

Implementation Strategy:

Since datastar-go's SSE type is designed for immediate response patterns (not long-lived streaming with multiple events), we'll need to maintain a hybrid approach:

• Use datastar's NewSSE() for proper header setup and SSE formatting
• Keep a registry of connected http.ResponseWriter instances
• Use datastar's event formatting methods while managing our own connection pool

Alternative Approach:

We could also use datastar's ServerSentEventDataWriter directly, which provides:

• Event(eventType string, data string) method for sending SSE events
• Proper SSE formatting
• Integration with http.ResponseWriter

This gives us the benefits of datastar's SSE infrastructure while maintaining our broadcast pattern.

Verification Plan

Automated Tests

# Build the application
go build -o zeroapp

# Run the application
./zeroapp

Manual Verification

1. Test notification stream endpoint:

   # Connect to notifications stream
   curl -N http://localhost:8081/stream/notifications
   
   # Should receive connected event and heartbeats

2. Test workflow status endpoint:

   # Connect to workflow stream
   curl -N http://localhost:8081/stream/workflow/order-123
   
   # Should receive connected event with order_id

3. Test broadcast functionality:

   • Trigger a notification broadcast (would need to integrate with existing handlers)
   • Verify all connected clients receive the notification
   • Test workflow status updates for specific order IDs

4. Test cleanup:

   • Connect multiple clients
   • Disconnect clients (Ctrl+C)
   • Verify server logs show proper cleanup
   • Check memory for leaked connections

Notes

Important

The datastar-go library is primarily designed for request-response patterns where you send SSE events as part of a single response. For long-lived streaming connections with multiple events sent over time, we'll need to carefully integrate datastar's formatting utilities while maintaining our own connection management.

Note

The current implementation uses custom event types (connected, notification, workflow_update). These should be preserved for frontend compatibility.