Skip to content
Tutorials Center
My learning

Topics

Lesson 110 of 147 ยท Web and Networking

Streaming, SSE and WebSockets

Stream HTTP responses in Go with http.Flusher, build Server-Sent Events, long polling and a broadcast hub with backpressure, and learn how WebSockets work and which libraries to use.

A normal HTTP exchange is a question and an answer: the client asks, the server replies once, and the connection becomes idle. Many features do not fit that shape. A progress bar needs updates while a job runs. A chat window must show messages the moment somebody else sends them. A dashboard wants a live feed of metrics. For all of these, the server has to push data to the client over time.

This lesson covers the tools Go gives you for that, from simplest to most powerful: streaming responses with http.Flusher, Server-Sent Events (SSE), long polling, and WebSockets. You will also build a small broadcast hub and see why every pushing server must decide what to do about slow clients. All runnable examples use httptest.NewServer and loopback connections, so they work inside the browser editor.

Streaming a response

When a handler writes to the http.ResponseWriter, the data is buffered. The server sends it when the handler returns or when the buffer fills up (about 4 KB). If you want the client to see data immediately, call Flush. The writer returned to your handler implements http.Flusher whenever the underlying connection supports streaming, which is the case for HTTP/1.1 and HTTP/2.

Since the handler does not know the total size when the first flush happens, the server switches to chunked transfer encoding: the body is sent in pieces, each prefixed with its length. The client sees ContentLength == -1 and a TransferEncoding of chunked.

Go Flushed versus buffered responses

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The buffered handler finishes before anything is flushed, so the server knows the length (21 bytes) and sets Content-Length. The streamed handler cannot, so the response is chunked. On the client, resp.Body is an ordinary reader, so a bufio.Scanner receives each line as it arrives instead of waiting for the end. Streaming therefore works with plain http.Get, with no special client API.

Instead of the type assertion w.(http.Flusher) you can write http.NewResponseController(w).Flush() (Go 1.20 and later). It works even when middleware has wrapped the writer, and it returns an error instead of panicking when flushing is not supported. The same controller can set per-request deadlines with SetWriteDeadline, which matters because a server-wide WriteTimeout would cut every long-lived stream.

Server-Sent Events

Streaming raw bytes works, but clients need a way to tell where one message ends. Server-Sent Events is a small text protocol on top of a streaming response. The server sets Content-Type: text/event-stream and writes events separated by a blank line. Each event consists of lines like these:

TEXT
: a comment, ignored by clients (often used as a keep-alive)
id: 7
event: price
retry: 3000
data: first line of the payload
data: second line of the payload

data: lines are joined with newlines. event: names the event type (the default is message), id: sets the last-event ID that a browser sends back in a Last-Event-ID header when it reconnects, and retry: suggests a reconnect delay in milliseconds. In the browser, the whole protocol is handled by new EventSource("/events"), which also reconnects automatically. SSE is one-directional (server to client) and plain HTTP, so it passes through proxies, load balancers and authentication middleware without special treatment.

The next example has a server that sends a fixed set of events and a client that parses the format by hand. Writing the parser once shows how little the protocol demands.

Go An SSE server and a hand-written client

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The parser follows the rules from the format description: ignore comments, split each line at the first colon, drop one leading space from the value, collect data lines and dispatch on the blank line. The stream ends when the handler returns and the server finishes the response.

Real feeds never end by themselves, so the handler must notice when the client goes away. The request's context is cancelled as soon as the connection closes. If the handler ignores it, the goroutine keeps writing into a dead connection forever and you leak one goroutine per disconnected viewer.

Go Detecting a client that disconnects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

After three events the client cancels its context, which closes the connection. On the server, r.Context().Done() fires, the handler closes gone and returns, and the program prints the confirmation. Every streaming handler needs this select. A few more practical points:

  • Keep-alive comments. Send : ping\n\n every 15 to 30 seconds so idle proxies and load balancers do not close the connection.
  • Proxy buffering. Reverse proxies such as nginx may buffer responses and hold your events back. Disable that for SSE routes (for nginx: proxy_buffering off, or send the header X-Accel-Buffering: no).
  • Resuming. When a browser reconnects, it sends Last-Event-ID. If your events have IDs, replay what the client missed from a buffer or database.
  • Connection limits. Browsers allow only about six HTTP/1.1 connections per host, and every open stream uses one. HTTP/2 removes that limit, so serve SSE over HTTP/2 in production.

Fan-out and backpressure

A stream rarely serves one client. A chat room or a price feed has many subscribers and many publishers, so you need a hub in the middle: publishers call Publish, and the hub sends a copy to each subscriber's channel. Each subscriber's goroutine then writes from its channel to its own HTTP connection.

This design hides a real question. What should happen when one subscriber is slow, say a phone on a bad network that cannot keep up? If Publish blocks on that subscriber's channel, one slow client stalls everybody. Unbounded buffers eventually exhaust memory. The classic answer is a bounded buffer per subscriber and a non-blocking send: if the buffer is full, the hub drops the slow subscriber (or drops the message, depending on what the application needs). Slowness is isolated and memory is bounded.

Go A broadcast hub that drops slow subscribers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The slow subscriber has room for two messages. When the third arrives, Publish finds the buffer full and drops it, closing its channel, so the reader sees what was queued and then the end of the stream. The fast subscriber is unaffected and receives all five messages in order. Note that Go ranges over a map in random order, so if several subscribers were slow, the order of the drop messages would vary; the outcome per subscriber would not.

In an SSE handler, the subscriber's loop would range over its channel and write each message with a Flush; when the channel closes, the handler returns and the client reconnects (and can resume from Last-Event-ID). This is the concurrency design from Concurrency Patterns applied to the network, and the channel mechanics are explained in Channels and Buffered Channels and select.

Long polling

Before SSE and WebSockets, long polling was the way to simulate pushing. The client sends a normal request; the server holds it open until something happens or a timeout expires; then the client immediately sends the next request. It uses only plain request/response HTTP, so it works everywhere, and it is a good fallback when streaming is blocked.

The handler below waits on a channel that the mailbox closes whenever a message arrives (a neat way to wake all waiters at once). If nothing arrives within the limit, it answers 204 No Content and the client simply polls again.

Go Long polling against a mailbox

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The first poll waits the full 150 ms and gets 204. The second is released after about 30 ms when hello arrives, which is why answered early is true. The third finds two messages waiting and returns immediately. Because the client always passes the index it has already seen, no message is delivered twice or lost between polls. The cost is one HTTP request per batch of messages plus the overhead of holding connections, which is why SSE or WebSockets are better for high-frequency data.

WebSockets

SSE only sends data from the server to the client. A WebSocket is a full-duplex, message-based channel: either side can send at any time, and messages can be text or binary. It begins as a normal HTTP request with an Upgrade: websocket header; the server answers 101 Switching Protocols, and from then on the same TCP connection carries WebSocket frames instead of HTTP.

Two details of the protocol can be implemented in a few lines of the standard library, which makes the format less magical. The server proves it understood the upgrade by hashing the client's Sec-WebSocket-Key with a fixed GUID, and clients mask every payload with a random 4-byte key. The program below computes the accept value and encodes and decodes a small frame, using the example values from the protocol specification (RFC 6455).

Go The WebSocket handshake and a masked frame

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The accept value s3pPLMBiTxaQ9kYGzzhZRbK+xOo= is exactly what the specification lists for that key, so any client that starts a handshake can check the server really speaks WebSocket. Opcode 1 means a text frame; others are binary (2), close (8), ping (9) and pong (10). Real frames also support longer lengths (two or eight extra bytes), fragmentation and compression. You should not write that yourself.

Which library to use

The standard library has no WebSocket package. The golang.org/x/net/websocket package exists but is documented as lacking features and is not recommended. Production code uses a third-party library, such as:

  • github.com/coder/websocket (formerly nhooyr.io/websocket): a small API based on context.Context, with helpers for JSON.
  • github.com/gorilla/websocket: the long-established library with an Upgrader and Conn type.

Because libraries cannot be downloaded in our sandbox, here is a read-only echo server and client with coder/websocket:

Go
// go get github.com/coder/websocket
func echo(w http.ResponseWriter, r *http.Request) {
	c, err := websocket.Accept(w, r, nil) // performs the upgrade
	if err != nil {
		return // Accept has already written the error response
	}
	defer c.CloseNow()

	for {
		typ, msg, err := c.Read(r.Context())
		if err != nil {
			return // closed by the peer or the context ended
		}
		if err := c.Write(r.Context(), typ, msg); err != nil {
			return
		}
	}
}

func client(ctx context.Context, url string) error {
	c, _, err := websocket.Dial(ctx, url, nil)
	if err != nil {
		return err
	}
	defer c.CloseNow()

	if err := c.Write(ctx, websocket.MessageText, []byte("ping")); err != nil {
		return err
	}
	_, reply, err := c.Read(ctx)
	fmt.Println(string(reply))
	return c.Close(websocket.StatusNormalClosure, "bye")
}

The structure is the same as in a TCP server (TCP Servers and Custom Protocols): one goroutine per connection, a read loop and cleanup on exit. Typical production rules apply:

  • Authenticate before upgrading (cookie or token on the handshake request) and check the Origin header so that other websites cannot open sockets on behalf of your logged-in users.
  • Set limits: maximum message size, read and write deadlines, ping/pong heartbeats to detect dead peers.
  • Use one writer per connection. Most libraries allow concurrent reads and writes but not several concurrent writers; funnel outgoing messages through a channel, just like the hub above.
  • Plan for scale: each socket holds a goroutine and memory. Tens of thousands per server are feasible in Go, but a load balancer needs sticky routing or a pub/sub backend (Redis, NATS) to deliver a message to a client connected to a different instance.

Choosing between them

Need Best fit
One-way updates (feeds, progress, notifications) SSE
Two-way, low-latency messages (chat, games, collaboration) WebSocket
Maximum compatibility, rare updates Long polling
Large downloads or uploads Plain streaming of the body

Start with the simplest one that works. SSE covers a surprising number of "real-time" requirements with far less machinery than WebSockets.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A handler writes three lines and calls Flush after each one. What does the client see in resp.ContentLength?

    Once the handler flushes, the headers are sent before the full size is known, so the server uses chunked transfer encoding and ContentLength is -1.
  2. 2. What marks the end of one event in the Server-Sent Events format?

    Events consist of field lines such as id, event and data, and a blank line dispatches the event. Lines starting with a colon are comments.
  3. 3. Why must a streaming handler select on r.Context().Done()?

    The request context is cancelled when the connection closes. Without this check the handler keeps looping for a viewer that is gone, leaking a goroutine per disconnected client.
  4. 4. In the broadcast hub, why does Publish use select with a default case?

    A non-blocking send isolates slow consumers. When a buffer is full, the hub drops that subscriber (or message) instead of stalling everyone.
  5. 5. Which statement about WebSockets in Go is correct?

    The upgrade is a normal HTTP request answered with 101 Switching Protocols on the same port. Go's standard library does not ship a WebSocket implementation, so production code uses a third-party package.

Summary

  • http.Flusher (or http.NewResponseController(w).Flush()) sends buffered data immediately; the response then uses chunked transfer encoding, and the client reads it incrementally from resp.Body.
  • Server-Sent Events are a text protocol on a streaming response: Content-Type: text/event-stream, id, event and data lines, a blank line to end each event. Browsers consume it with EventSource and reconnect automatically.
  • Streaming handlers must watch r.Context().Done() to stop when the client leaves, and should send keep-alive comments and expect proxy buffering problems.
  • A hub fans messages out to subscribers; give each a bounded buffer and use a non-blocking send so one slow client cannot stall the rest (backpressure).
  • Long polling holds a normal request open until data arrives or a timeout fires. It is the most compatible option and the least efficient.
  • WebSockets upgrade an HTTP connection into a two-way message channel. The standard library has no implementation, so use coder/websocket or gorilla/websocket, authenticate during the handshake, check the origin, set limits and keep one writer per connection.

Next: TCP Servers and Custom Protocols