sseclient: bitbucket.org/advbet/sseclient Index | Examples | Files

package sseclient

import "bitbucket.org/advbet/sseclient"

Package sseclient is library for consuming SSE streams.

Key features:

Synchronous execution. Reconnecting, event parsing and processing is executed in single go-routine that started the stream. This gives freedom to use any concurrency and synchronization model.

Go context aware. SSE streams can be optionally given a context on start. This gives flexibility to support different stream stopping mechanisms.

Code:

package main

import (
    "context"
    "log"
    "time"
)

func errorHandler(err error) error {
    log.Printf("error : %s", err)
    return nil
}

func eventHandler(event *Event) error {
    log.Printf("event : %s : %s : %d bytes of data", event.ID, event.Event, len(event.Data))
    return nil
}

func main() {
    c := New("https://example.net/stream", "")
    ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
    defer cancel()
    c.Start(ctx, eventHandler, errorHandler)
}

Index

Examples

Package Files

client.go

Variables

var MalformedEvent = errors.New("incomplete event at the end of the stream")

MalformedEvent error is returned if stream ended with incomplete event.

type Client Uses

type Client struct {
    URL         string
    LastEventID string
    Retry       time.Duration
    HTTPClient  *http.Client
    Headers     http.Header
}

Client is used to connect to SSE stream and receive events. It handles HTTP request creation and reconnects automatically.

Client struct should be created with New method or manually.

func New Uses

func New(url, lastEventID string) *Client

New creates SSE stream client object. It will use given URL and last event ID values, default HTTP client from http package and 2 second retry timeout. This method only creates Client struct and does not start connecting to the SSE endpoint.

func (*Client) Start Uses

func (c *Client) Start(ctx context.Context, eventFn EventHandler, errorFn ErrorHandler) error

Start connects to the SSE stream. This function will block until SSE stream is stopped. Stopping SSE stream is possible by cancelling given stream context or by returning some error from the error handler callback. Error returned by the error handler is passed back to the caller of this function.

func (*Client) Stream Uses

func (c *Client) Stream(ctx context.Context, buf int) <-chan StreamMessage

Stream is non-blocking SSE stream consumption mode where events are passed through a channel. Stream can be stopped by cancelling context.

Parameter buf controls returned stream channel buffer size. Buffer size of 0 is a good default.

type ErrorHandler Uses

type ErrorHandler func(error) error

ErrorHandler is a callback that gets called every time SSE stream encounters an error including errors returned by EventHandler function. Network connection errors and response codes 500, 502, 503, 504 are not treated as errors.

If error handler returns nil, error will be treated as handled and stream will continue to be processed (with automatic reconnect).

If error handler returns error it is treated as fatal and stream processing loop exits returning received error up the stack.

This handler can be used to implement complex error handling scenarios. For simple cases ReconnectOnError or StopOnError are provided by this library.

Users of this package have to provide this function implementation.

var (
    ReconnectOnError ErrorHandler = func(error) error { return nil }
    StopOnError      ErrorHandler = func(err error) error { return err }
)

List of commonly used error handler function implementations.

type Event Uses

type Event struct {
    ID    string
    Event string
    Data  []byte
}

Event object is a representation of single chunk of data in event stream.

type EventHandler Uses

type EventHandler func(e *Event) error

EventHandler is a callback that gets called every time event on the SSE stream is received. Error returned from handler function will be passed to the error handler.

Users of this package have to provide this function implementation.

type StreamMessage Uses

type StreamMessage struct {
    Event *Event
    Err   error
}

StreamMessage stores single SSE event or error.

Package sseclient imports 9 packages (graph). Updated 2019-04-26. Refresh now. Tools for package owners.