Add Built-in SSE Support in GoFr

[coolwednesday]

Description

GoFr currently does not provide first-class support for Server-Sent Events (SSE). While SSE can be implemented manually using the underlying net/http, developers must handle headers, flushing, and connection lifecycle themselves.

It would be helpful to provide a built-in SSE helper or streaming API that:

• Automatically sets required headers (text/event-stream)
• Handles flushing
• Detects client disconnects
• Optionally supports named events and JSON payloads

This would reduce boilerplate and improve developer experience for real-time use cases such as notifications, dashboards, and live updates.

[IronwallxR5]

@coolwednesday, I would like to work on this issue.

[coolwednesday]

@coolwednesday, I would like to work on this issue.

Hi @IronwallxR5,

I just wanted to check if you’re currently working on any existing issue. If not, I’d be happy to assign this one to you. I noticed your comments across multiple issues, so I just wanted to clarify before proceeding.

Thank you 😊

[IronwallxR5]

Nope, Currently i am not working on any issue .

[coolwednesday]

Cool then. Assigned it to you.

Nope, Currently i am not working on any issue .

[IronwallxR5]

Cool then. Assigned it to you.

Nope, Currently i am not working on any issue .

Thanks !!

[coolwednesday]

Cool then. Assigned it to you.

Nope, Currently i am not working on any issue .

Thanks !!

We would like a proposal attached in the issue ticket for the design before you create a PR.

[IronwallxR5]

Design Proposal: Built-in SSE Support

Problem

Right now there's no first-class way to do Server-Sent Events in GoFr. If someone wants to stream events to a browser, they have to drop down to raw http.ResponseWriter, manage flushing themselves, deal with client disconnects manually, etc. It doesn't feel like GoFr at all.

We already have app.WebSocket() for bidirectional streaming. SSE fills the gap for simpler one-way scenarios — live dashboards, progress bars, notification feeds — where WebSockets are overkill.

Goal

A developer should be able to write something like this and have it just work:

app.SSE("/events", func(ctx *gofr.Context, stream *gofr.SSEStream) error {
    for i := 0; i < 10; i++ {
        if err := stream.SendEvent("counter", i); err != nil {
            return err
        }
        time.Sleep(time.Second)
    }
    return nil
})

No fiddling with response headers, flushing, or context cancellation. The framework handles all of that.

Design

Registration

New method on *App:

func (a *App) SSE(pattern string, handler SSEHandler)

This registers a GET route (SSE is always GET per spec). Follows the same pattern as app.WebSocket() — dedicated method, specific handler signature.

Handler signature

type SSEHandler func(ctx *Context, stream *SSEStream) error

The handler gets the same *Context everyone already uses, plus a stream to push events into. Return nil when done, return an error if something goes wrong.

SSEStream — channel-based broker

This is where the interesting design decision is. I went with a channel-based approach (inspired by this OneUptime article):

type SSEStream struct {
    events chan string   // buffered channel (64 slots)
    done   chan struct{} // closed when connection ends
}

The handler goroutine pushes formatted events into the channel via Send()/SendData()/SendEvent()/SendComment(). A synchronous drain loop in ServeHTTP reads from the channel and writes to the wire.

Why channels instead of writing directly to the ResponseWriter?

• Decouples production from I/O. The handler doesn't need to worry about flush timing or write errors.
• Natural backpressure. Buffered channel absorbs bursts; if the client can't keep up the channel fills and Send() blocks (or returns an error via the done channel).
• Clean shutdown. When the handler returns, it closes the events channel. The drain loop sees that and exits.

The done channel prevents a goroutine leak edge case: if the client disconnects while the events buffer is full, Send() would block forever on the channel. The select on done lets it bail out immediately.

Drain loop

Runs synchronously in ServeHTTP. Three-way select:

1. Event from channel → write to wire, flush
2. Heartbeat tick (15s) → write : heartbeat\n\n, flush
3. Context cancelled → client disconnected, return

The heartbeat keeps the connection alive through proxies/load balancers that kill idle connections. 15 seconds is a common default.

SSE wire format

SSEEvent struct covers the full spec:

type SSEEvent struct {
    Name  string   // event: field
    Data  any      // data: field (strings pass through, everything else gets JSON-marshaled)
    ID    string   // id: field
    Retry int      // retry: field (ms)
}

For data serialization: strings and []byte go through as-is, anything else gets json.Marshal()'d. Multiline strings are split properly data: line1\ndata: line2\n.
Middleware compatibility

GoFr's StatusResponseWriter wraps the real ResponseWriter for logging. SSE needs access to the underlying http.Flusher. I'm adding two methods to StatusResponseWriter:

• Flush() — delegates to the inner writer's Flusher
• Unwrap() — returns the inner writer so http.ResponseController can reach through
  http.ResponseController handles the unwrapping automatically — we just need to provide Unwrap(). This is the same approach the stdlib recommends.

Panic recovery

Same pattern as the regular handler. defer/recover in the handler goroutine catches panics, logs them, and sends a sentinel error through the handlerDone channel so the drain loop can shut down cleanly.

Error logging

Reuses the same logError pattern from handler.go — respects GoFr's log level classification so custom error types can control their log severity.

Tracing

The SSE handler runs within the existing OTel span from the request. The trace ID is extracted for log correlation. No new spans are created — the long-lived connection is the span.

What I Considered But Didn't Do

• Automatic JSON mode / content negotiation — Kept it simple. The handler controls what data goes in. If you want JSON, pass a struct to Send() and it gets marshaled.
• Retry/reconnection logic on the server — That's a client concern per the SSE spec. The server can set the retry field via SSEEvent.Retry and that's enough.
• Per-event flush control — Every event gets flushed immediately. In practice that's what you want for SSE. Batching would add complexity for a niche use case.
• Custom heartbeat interval — Hardcoded at 15s for now. Could be made configurable later if anyone needs it, but 15s works for most proxies.

Testing

• Unit tests for formatSSEData and formatEvent (16 subtests covering strings, structs, byte slices, multiline, nil, all SSE fields)
• Stream methods: Send, SendData, SendEvent, SendComment, concurrent sends, send-after-close
• Goroutine leak test for the blocked-sender edge case
• Full HTTP handler tests: normal flow, client disconnect, handler error, panic recovery, non-flushable writer, heartbeat
  Integration tests using httptest.Server with real HTTP connections

[aryanmehrotra]

Having a new method just for this doesn't seem to be better approach the GET, POST etc which are on the type of method, SSE is a way to respond not the method type.

[IronwallxR5]

Thanks for the feedback @aryanmehrotra , makes sense. SSE is a response format, not an HTTP method, so app.SSE() alongside app.GET() is the wrong abstraction.

I looked at two alternatives:

ctx.Stream() — doesn't work cleanly. GoFr writes the HTTP response after the handler returns, so if the handler flushes SSE data mid-execution and then returns nil, nil, the Responder would try to write a JSON response on top and corrupt the stream.

Returning a custom type — seems like the right fit for GoFr's existing pattern. The handler stays the normal func(ctx *Context) (any, error) signature and just returns an SSEResponse struct containing the producer function. The Responder detects this type and takes over — sets the headers, runs the drain loop, handles flushing. No new routing method, no context bloat.

app.GET("/events", func(ctx *gofr.Context) (any, error) {
    return gofr.SSEResponse(func(stream *gofr.SSEStream) error {
        // produce events
        return nil
    }), nil
})

Does this direction look right to you, or did you have something else in mind? I'll hold off on updating the code until we align on the design.