Server-Sent Events

One connection, many events

The client makes a normal GET; the server keeps the response open and writes text/event-stream frames over time. The browser’s built-in EventSource parses them and auto-reconnects if the link drops:

graph LR
C["client<br/>EventSource(/events)"] -->|"GET, stays open"| S["server"]
S -->|"data: 1"| C
S -->|"data: 2"| C
S -->|"data: 3 …"| C

Each event is just text — data: lines ended by a blank line; optional event: (a name) and id: (for resume):

event: tick
id: 42
data: {"price": 101.5}

Stream events from a handler

An SSE handler sets the content type, then writes-and-flushes each event. We can run the exact handler in-process and capture the stream it produces:

package main

import (
"fmt"
"net/http"
"net/http/httptest"
)

// events streams three SSE frames over one long-lived response.
func events(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/event-stream")
w.Header().Set("Cache-Control", "no-cache")
flusher, _ := w.(http.Flusher) // real servers push each event out now
for i := 1; i <= 3; i++ {
	fmt.Fprintf(w, "event: tick\ndata: %d\n\n", i)
	if flusher != nil {
		flusher.Flush()
	}
}
}

func main() {
// run the handler in-process; the recorder captures the event stream
rec := httptest.NewRecorder()
events(rec, httptest.NewRequest("GET", "/events", nil))

fmt.Println("content-type:", rec.Header().Get("Content-Type"))
fmt.Print(rec.Body.String())
}

On a real server

The playground above runs the handler in-process; in production it registers on a normal route and loops — pushing an event whenever new data arrives on a channel, and returning the moment the client disconnects (so a closed tab frees the goroutine).

Where does that channel come from? You need something that fans one source of updates out to every connected client — a pub/sub hub (the broker from the Pub/Sub pattern). broker.Subscribe() returns a new channel for this client, and broker.Unsubscribe closes it when they leave:

// Event is whatever you broadcast. The broker is a pub/sub hub whose
// Subscribe() hands each client its own channel of events.
type Event struct {
	ID   int
	Name string
	Data string
}

func sseHandler(broker *Broker) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/event-stream")
		w.Header().Set("Cache-Control", "no-cache")
		w.Header().Set("Connection", "keep-alive")
		flusher := w.(http.Flusher)

		updates := broker.Subscribe()       // this client's own channel
		defer broker.Unsubscribe(updates)   // clean up when they disconnect

		for {
			select {
			case ev := <-updates: // new data — send it as an event
				fmt.Fprintf(w, "id: %d\nevent: %s\ndata: %s\n\n", ev.ID, ev.Name, ev.Data)
				flusher.Flush() // push it out immediately
			case <-r.Context().Done(): // client disconnected — stop
				return
			}
		}
	}
}

// wire it up: mux.Handle("GET /events", sseHandler(broker))

Broker is just a mutex-guarded set of subscriber channels with Subscribe/Unsubscribe/Publish methods — see the Pub/Sub pattern for a full implementation.

The browser consumes it with the built-in EventSource, which parses the frames and reconnects on its own:

const es = new EventSource("/events");
es.addEventListener("tick", (e) => console.log("tick:", e.data));
es.onerror = () => console.log("reconnecting…"); // the browser retries for you

Set timeouts carefully so the long-lived response isn’t cut off, and drain cleanly on shutdown (see graceful shutdown).

SSE vs WebSockets vs polling

See also

• WebSockets — when you need the client to send too.
• polling — the lowest-tech option for infrequent updates.
• Pub/Sub pattern — the broker that fans updates out to each subscriber.
• graceful shutdown — draining long-lived streams on exit.

Next: the simplest approach of all — polling.

Related topics