sse

README

sse

Golang HTML5 Server-Sent-Events

According to the following specification: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events (recommended by https://www.w3.org/TR/2015/REC-eventsource-20150203/)

Example

See example for an example.

Documentation

Overview

Package sse implements a server and client for the HTML5 Server-Sent-Events protocol. More protocol information available at https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events

Index

• Variables
• type Client
  • func Connect(client *http.Client, request *http.Request) (*Client, error)
  • func NewClient(r io.Reader) *Client
  • func (c *Client) Close() error
  • func (c *Client) Event() (ev Event, err error)
• type ErrIllegalRune
  • func (err ErrIllegalRune) Error() string
• type Event
  • func (ev Event) Validate() (err error)
  • func (ev Event) WriteTo(w io.Writer) (int64, error)
• type Handler
  • func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ResponseWriteFlusher
  • func Flusher(w http.ResponseWriter) (ResponseWriteFlusher, error)
• type ScannedEvent
• type Scanner
  • func NewScanner(r io.Reader) *Scanner
  • func (s *Scanner) Event() (ev ScannedEvent, err error)
• type Sender
  • func NewSender(w http.ResponseWriter) (*Sender, error)
  • func (s *Sender) Flush()
  • func (s *Sender) SendEvent(event Event) error
  • func (s *Sender) SendJSON(msg interface{}) error
  • func (s *Sender) SendQuick(event Event) error

Variables

var ErrClosedClient = errors.New("client closed")

ErrClosedClient is an error indicating that the client has been used after it was closed.

var ErrFlushNotSupported = errors.New("flush not supported")

ErrFlushNotSupported indicates that the provided http.ResponseWriter does not implement http.Flusher

var ErrNoData = errors.New("event contains no data")

ErrNoData is an error which indicates that an Event has an empty Data field

var ErrNotNCName = errors.New("name is not a valid NCName")

ErrNotNCName is an error indicating that the name of an Event is not a valid NCName See https://www.w3.org/TR/REC-xml-names/#NT-NCName

var ErrNotSSE = errors.New("content type is not 'text/event-stream'")

ErrNotSSE is an error returned when a client receives a non-SSE response

Types

type Client

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

Client is a SSE client

func Connect

func Connect(client *http.Client, request *http.Request) (*Client, error)

Connect performs an SSE request and returns a Client.

func NewClient

func NewClient(r io.Reader) *Client

NewClient returns a client which will parse Event from the io.Reader

func (*Client) Close

func (c *Client) Close() error

Close closes the client

func (*Client) Event

func (c *Client) Event() (ev Event, err error)

Event reads an event from the stream.

type ErrIllegalRune

type ErrIllegalRune struct {
	Name string //Name of field containing rune
	In   string //The string the rune is in
	Rune rune   //The illegal rune
}

ErrIllegalRune is an error type which indicates that an illegal rune was in an Event field

func (ErrIllegalRune) Error

func (err ErrIllegalRune) Error() string

type Event

type Event struct {
	Name string //Name of the event, referred to as "event" (optional)
	Data string //Event data, referred to as "data" (required)
}

Event is an SSE event. See https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events for more info. The "id" and "retry" settings are not currently implemented.

func (Event) Validate

func (ev Event) Validate() (err error)

Validate checks that an event is valid. An Event must have a Data field and fields cannot contain '\n' '\r' or '\0'. Data field is special and newlines are legal. Name must be a valid NCName (see ErrNotNCName).

func (Event) WriteTo

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

WriteTo allows the event to implement io.WriterTo

type Handler

type Handler func(*Sender, *http.Request)

Handler is an http.Handler which uses SSE. If there is an error in NewSender, an http.StatusInternalServerError is sent.

func (Handler) ServeHTTP

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type ResponseWriteFlusher

type ResponseWriteFlusher interface {
	http.ResponseWriter
	http.Flusher
}

ResponseWriteFlusher is an interface combining http.ResponseWriter and http.Flusher. Any http.ResponseWriter used for SSE must also implement http.Flusher.

func Flusher

func Flusher(w http.ResponseWriter) (ResponseWriteFlusher, error)

Flusher tries to get a ResponseWriteFlusher from an http.ResponseWriter

type ScannedEvent

type ScannedEvent struct {
	Type     string // event type
	Data     string // data buffer
	ID       string // last event ID
	IDSet    bool   // was the last event ID set
	Retry    int    // event stream's reconnection time
	RetrySet bool   // was the Retry delay set
}

ScannedEvent is an SSE event. See https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events for more info.

type Scanner

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

Scanner parses an event stream

func NewScanner

func NewScanner(r io.Reader) *Scanner

NewScanner returns a Scanner which will parse Event from the io.Reader

func (*Scanner) Event

func (s *Scanner) Event() (ev ScannedEvent, err error)

Event reads an event from the stream.

type Sender

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

Sender is an HTML5 Server Sent Events sender

func NewSender

func NewSender(w http.ResponseWriter) (*Sender, error)

NewSender creates an SSE event sender using an http.ResponseWriter

func (*Sender) Flush

func (s *Sender) Flush()

Flush flushes the events. This is only necessary after SendQuick.

func (*Sender) SendEvent

func (s *Sender) SendEvent(event Event) error

SendEvent sends an event. The event is immediately flushed to the client.

func (*Sender) SendJSON

func (s *Sender) SendJSON(msg interface{}) error

SendJSON sends a JSON event. The event is immediately flushed to the client.

func (*Sender) SendQuick

func (s *Sender) SendQuick(event Event) error

SendQuick sends an event without flushing. When using this method, you must manually call Flush to writr the events. The purpose of this method is to speed up sending large batches of events.