sse

Documentation

Overview

Package sse provides support for Server-Sent Events, as a handler for net/http, and a client that can read SSE events from net/http responses.

SSE is specified here: http://www.w3.org/TR/eventsource/

The package implements only partial support for SSE, specifically the client and server do not handle retries or event buffering.

Index

• Variables
• func Start(w http.ResponseWriter, r *http.Request) error
• func Write(w http.ResponseWriter, e *Event) error
• type Client
  • func New(r *http.Response) (*Client, error)
  • func (c *Client) ReadEvent() (*Event, error)
• type Event
  • func (e *Event) Marshal() []byte
  • func (e *Event) String() string
  • func (e *Event) WriteTo(w io.Writer) (int64, error)
• type ProtocolError
  • func (pe *ProtocolError) Error() string

Examples

• Start

Variables

var ErrNotAcceptable = errors.New("sse: invalid content-type")

ErrNotAcceptable occurs when the incoming request does not Accept text/event-stream

Functions

func Start

func Start(w http.ResponseWriter, r *http.Request) error

Start asserts that the client wants SSE, and if so, begins writing an SSE stream with the appropriate response headers. It performs a forced flush on the stream to ensure that the client receives the headers immediately.

Example

http.HandleFunc("/example/startsse", func(w http.ResponseWriter, r *http.Request) {
	err := Start(w, r)
	if err != nil {
		w.WriteHeader(http.StatusNotFound)
		return
	}
	ticker := time.NewTicker(time.Second)
	for {
		select {
		case <-ticker.C:
			helloWorld := &Event{Data: []byte("hello world")}
			helloWorld.WriteTo(w)
		case <-r.Context().Done():
			ticker.Stop()
			return
		}
	}
})

func Write

func Write(w http.ResponseWriter, e *Event) error

Write sends an event to an http ResponseWriter, flushing afterward.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client provides a handle to methods that are bound to a single SSE stream.

func New

func New(r *http.Response) (*Client, error)

New constructs a new SSE client against the http.Response. It returns an error if the response is not a valid SSE response, for example carrying the incorrect content type, or not having a response body stream. In cases where the error is an SSE protocol issue, ProtocolError is returned.

func (*Client) ReadEvent

func (c *Client) ReadEvent() (*Event, error)

ReadEvent parses the next event out of the response body, blocking if none is yet available. It returns either an Event or an error. error is either a ProtocolError or one of various IO errors, such as io.EOF.

type Event

type Event struct {
	Event string
	Data  []byte
	ID    string
	Retry *int
}

Event represents a single Server-Sent Event.

func (*Event) Marshal

func (e *Event) Marshal() []byte

Marshal returns a string in the SSE wire format, with the Data field repeated for an ocurrences of line breaks in the bytes.

func (*Event) String

func (e *Event) String() string

String returns the same format as Marshal

func (*Event) WriteTo

func (e *Event) WriteTo(w io.Writer) (int64, error)

WriteTo marshals the event and writes it to the given stream. HTTP users will likely prefer to use sse.Write instead, as that handles flushing the stream.

type ProtocolError

type ProtocolError struct {
	Response *http.Response
	Err      error
}

ProtocolError provides details of any protocol error that has occurred, the original Response object and an Error that contains a description of the problem.

func (*ProtocolError) Error

func (pe *ProtocolError) Error() string