eventsource

README

Eventsource

Package eventsource provides an implementation to Server-sent events using goroutines to handle client (un)subscription and forwarding events to clients.

For more information about Eventsource / SSE check the MDN documentation

Documentation

GoDocs

For an example of a server sending and receiving messages check: Replay Poker Eventsource

Documentation

Overview

Package eventsource provides an implementation to Server-sent events using goroutines to handle client (un)subscription and forward events to clients. For more information about Eventsource / SSE check the MDN documentation: https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events

Index

• Constants
• Variables
• type ChannelSubscriber
• type DefaultEvent
  • func (e DefaultEvent) Bytes() []byte
  • func (e DefaultEvent) Clients(clients []client) []client
• type DefaultHttpOptions
  • func (h DefaultHttpOptions) Bytes(req *http.Request) []byte
• type DefaultMetrics
  • func (DefaultMetrics) ClientCount(int)
  • func (DefaultMetrics) EventDone(e Event, _ time.Duration, durations []time.Duration)
• type Event
• type Eventsource
  • func (es *Eventsource) Errors() chan error
  • func (es *Eventsource) Send(event Event)
  • func (es *Eventsource) ServeHTTP(res http.ResponseWriter, req *http.Request)
  • func (es *Eventsource) Start()
• type HttpOptions
• type Metrics
• type NoChannels
  • func (n NoChannels) ParseRequest(req *http.Request) []string
• type NoopMetrics
  • func (NoopMetrics) ClientCount(int)
  • func (NoopMetrics) EventDone(Event, time.Duration, []time.Duration)
• type QueryStringChannels
  • func (n QueryStringChannels) ParseRequest(req *http.Request) []string

Constants

const (
	// HTTP HEADER sent to browser to upgrade the protocol to event-stream
	HEADER = `HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive`
)

Variables

var HijackingError = "webserver doesn't support hijacking"

A HijackingError is displayed when the browser doesn't support connection hijacking. See http://golang.org/pkg/net/http/#Hijacker

Types

type ChannelSubscriber

type ChannelSubscriber interface {
	ParseRequest(*http.Request) []string
}

ChannelSubscriber interface is used to determine which channels a client has subscribed to. This package has two built-in implementations: NoChannels and QueryStringChannels, but you can implement your own.

type DefaultEvent

type DefaultEvent struct {
	ID       int
	Name     string
	Message  []byte
	Channels []string
	Compress bool
}

DefaultEvent implements the Event interface

func (DefaultEvent) Bytes

func (e DefaultEvent) Bytes() []byte

Bytes returns the text/stream message to be sent to the client. If the event has name, it is added first, then the data. Optionally, the data can be compressed using zlib.

func (DefaultEvent) Clients

func (e DefaultEvent) Clients(clients []client) []client

Clients selects clients that have at least one channel in common with the event or all clients if the event has no channel.

type DefaultHttpOptions

type DefaultHttpOptions struct {
	// Cors sets if the server has Cross-Origin Resource Sharing enabled
	Cors bool

	// Internet Explorer < 10 and Chrome < 13 needs a message padding to successfully establish a
	// text stream connection See
	//http://blogs.msdn.com/b/ieinternals/archive/2010/04/06/comet-streaming-in-internet-explorer-with-xmlhttprequest-and-xdomainrequest.aspx
	OldBrowserSupport bool

	// Retry is the amout of time in milliseconds that the client must retry a
	// reconnection
	Retry int
}

func (DefaultHttpOptions) Bytes

func (h DefaultHttpOptions) Bytes(req *http.Request) []byte

The Bytes function writes a header and body to the browser to establish a text/stream connection with retry option and CORS if enabled.

type DefaultMetrics

type DefaultMetrics struct{}

DefaultMetrics implements the Metrics interface and logs events to the stdout.

func (DefaultMetrics) ClientCount

func (DefaultMetrics) ClientCount(int)

ClientCount does nothing.

func (DefaultMetrics) EventDone

func (DefaultMetrics) EventDone(e Event, _ time.Duration, durations []time.Duration)

EventDone logs to stdout the avg time an event to be sent to clients. Clients with error are ignored.

type Event

type Event interface {
	// Bytes returns the data to be written on the clients connection
	Bytes() []byte

	// Clients receives a list of clients and return a filtered list.
	Clients([]client) []client
}

Event is an interface that defines what the event payload is and to which connections it must be sent

type Eventsource

type Eventsource struct {

	// Interface that implements how channels are assigned to clients. It
	// defaults to NoChannels, meaning all events must be global.
	ChannelSubscriber

	// Interface that implements what options are sent during the initial http
	// handshaking. See DefaultHttpOptions for built-in options.
	HttpOptions

	// Interface that implements basic metrics for events
	Metrics
	// contains filtered or unexported fields
}

An Eventsource is a high-level server abstraction. It can be used as a Handler for a http route and to send events to clients. Multiple servers can coexist and be used on more than one end-point.

func (*Eventsource) Errors

func (es *Eventsource) Errors() chan error

func (*Eventsource) Send

func (es *Eventsource) Send(event Event)

Send forwards an event to clients

func (*Eventsource) ServeHTTP

func (es *Eventsource) ServeHTTP(res http.ResponseWriter, req *http.Request)

ServeHTTP implements the http handle interface. If the connection supports hijacking, it sends an initial header and body to switch to the text/stream protocol and start streaming.

func (*Eventsource) Start

func (es *Eventsource) Start()

Start sets all undefined options to their defaults and configure the underlining server to start listening to events

type HttpOptions

type HttpOptions interface {
	Bytes(*http.Request) []byte
}

type Metrics

type Metrics interface {
	ClientCount(int)
	EventDone(Event, time.Duration, []time.Duration)
}

Metrics interface allows basic instrumentation of the server

type NoChannels

type NoChannels struct{}

NoChannels implements the ChannelSubscriber interface by always returning an empty list of channels. This is useful for implementing an eventsource with global messages only.

func (NoChannels) ParseRequest

func (n NoChannels) ParseRequest(req *http.Request) []string

ParseRequest returns an empty list of channels.

type NoopMetrics

type NoopMetrics struct{}

NoopMetrics implements the Metrics interface and does nothing. Useful for disable metrics.

func (NoopMetrics) ClientCount

func (NoopMetrics) ClientCount(int)

ClientCount does nothing.

func (NoopMetrics) EventDone

func (NoopMetrics) EventDone(Event, time.Duration, []time.Duration)

EventDone does nothing.

type QueryStringChannels

type QueryStringChannels struct {
	Name string
}

QueryStringChannels implements the ChannelSubscriber interface by parsing the request querystring and extracting channels separated by commas. Eg.: /?channels=a,b,c

func (QueryStringChannels) ParseRequest

func (n QueryStringChannels) ParseRequest(req *http.Request) []string

ParseRequest parses the querystring and extracts the Name params, spliting it by commas.