Documentation
¶
Overview ¶
Package sse holds the server-sent-events wire format shared by every stream this server serves — session events and the devtools console alike.
It is deliberately only the wire: framing, the resume header, and the flush-and-keepalive contract. What to stream, and when a stream is over, is the caller's business.
Index ¶
Constants ¶
const DefaultKeepalive = 20 * time.Second
DefaultKeepalive is how often an otherwise silent stream reassures the proxies between here and the browser that the connection is alive. A trace that ran for seconds never needed one; a tail can sit idle for minutes, and the common idle timeout in front of it is a minute.
const KeepaliveFrame = ": ping\n\n"
KeepaliveFrame is a comment frame: the one thing that can be written into an event stream without being an event.
Write it from the same goroutine — ideally the same select — that writes event frames. A ping emitted from a timer goroutine can land between a frame's id and its data, which splits the frame and desynchronises the client for the life of the connection.
Variables ¶
This section is empty.
Functions ¶
func Begin ¶
func Begin(w http.ResponseWriter) (http.Flusher, error)
Begin writes the event-stream headers and returns the flusher the stream must call after every frame.
It lifts the server's write deadline for this response. A stream is open for as long as it has something to follow, and a server WriteTimeout sized for ordinary requests would otherwise cut every stream at that age. A writer that cannot set deadlines has none to lift; any other failure is returned, and the caller should end the response.
It panics rather than degrading when the writer cannot flush: an unflushed event stream looks like a hung request, which is far harder to diagnose than a stack trace naming the middleware that swallowed the Flusher.
func LastEventSequence ¶
LastEventSequence reads the resume header a browser sends after a dropped connection. Anything that is not a sequence is a client the server cannot answer correctly — replaying the whole ring instead would silently duplicate every event it already has.
func WriteFrame ¶
WriteFrame writes one frame; an error means the client disconnected and the stream should stop.
func WriteNDJSON ¶
func WriteNDJSON[T any](w http.ResponseWriter, filename string, items []T)
WriteNDJSON serves the same events as a downloadable file, for a caller that wants the stream's contents without following it.
Source Files