recws

README

recws

Reconnecting WebSocket is a websocket client based on gorilla/websocket that will automatically reconnect if the connection is dropped.

Installation

go get github.com/icamys/recws

Examples

See basic usage example.

License

recws is open-source software licensed under the MIT license.

Documentation

Overview

Package recws provides websocket client based on gorilla/websocket that will automatically reconnect if the connection is dropped.

Index

• Variables
• type ConnectionOptions
• type Option
  • func WithDebugLogFn(fn func(string)) Option
  • func WithErrorLogFn(fn func(error, string)) Option
  • func WithHandshakeTimeout(to time.Duration) Option
  • func WithKeepAliveTimeout(kat time.Duration) Option
  • func WithOnConnectCallback(cb func()) Option
  • func WithProxy(p func(*http.Request) (*url.URL, error)) Option
  • func WithReconnectIntervalFactor(factor float64) Option
  • func WithReconnectIntervalMax(interval time.Duration) Option
  • func WithReconnectIntervalMin(interval time.Duration) Option
  • func WithRespectServerClosure(r bool) Option
  • func WithTLSClientConfig(c *tls.Config) Option
• type RecConn
  • func New(url string, requestHeader http.Header, options ...Option) (RecConn, error)

Variables

var (
	// ErrNotConnected is returned when the application read/writes
	// a message and the connection is closed
	ErrNotConnected = errors.New("websocket: not connected")
)

Types

type ConnectionOptions

type ConnectionOptions struct {
	// ReconnectIntervalMin specifies the initial reconnecting interval,
	// default to 2 seconds.
	ReconnectIntervalMin time.Duration
	// ReconnectIntervalMax specifies the maximum reconnecting interval,
	// default to 30 seconds.
	ReconnectIntervalMax time.Duration
	// ReconnectIntervalFactor specifies the rate of increase of the reconnection
	// interval, default to 1.5.
	ReconnectIntervalFactor float64
	// RespectServerClosure specifies whether the client should stop trying to reconnect
	// if the server asked so by sending the normal closure message.
	RespectServerClosure bool
	// HandshakeTimeout specifies the duration for the handshake to complete,
	// default to 2 seconds.
	HandshakeTimeout time.Duration
	// Proxy specifies the proxy function for the dialer
	// defaults to ProxyFromEnvironment.
	Proxy func(*http.Request) (*url.URL, error)
	// Client TLS config to use on reconnect.
	TLSClientConfig *tls.Config
	// OnConnectCallback fires after the connection successfully establish.
	OnConnectCallback func()
	// KeepAliveTimeout is an interval for sending ping/pong messages
	// disabled if 0.
	KeepAliveTimeout time.Duration
	// LogFn is a set of functions to run for different logging levels.
	LogFn logFnOptions
}

type Option

type Option func(c *ConnectionOptions)

func WithDebugLogFn

func WithDebugLogFn(fn func(string)) Option

func WithErrorLogFn

func WithErrorLogFn(fn func(error, string)) Option

func WithHandshakeTimeout

func WithHandshakeTimeout(to time.Duration) Option

func WithKeepAliveTimeout

func WithKeepAliveTimeout(kat time.Duration) Option

func WithOnConnectCallback

func WithOnConnectCallback(cb func()) Option

func WithProxy

func WithProxy(p func(*http.Request) (*url.URL, error)) Option

func WithReconnectIntervalFactor

func WithReconnectIntervalFactor(factor float64) Option

func WithReconnectIntervalMax

func WithReconnectIntervalMax(interval time.Duration) Option

func WithReconnectIntervalMin

func WithReconnectIntervalMin(interval time.Duration) Option

func WithRespectServerClosure

func WithRespectServerClosure(r bool) Option

func WithTLSClientConfig

func WithTLSClientConfig(c *tls.Config) Option

type RecConn

type RecConn interface {
	// Close closes the underlying network connection without
	// sending or waiting for a close frame.
	Close(forever bool)

	// CloseAndReconnect closes the underlying connection and tries to reconnect.
	CloseAndReconnect()

	// Shutdown gracefully closes the connection by sending the websocket.CloseMessage.
	// The writeWait param defines the duration before the deadline of the write operation is hit.
	Shutdown(writeWait time.Duration)

	// ReadMessage is a helper method for getting a reader
	// using NextReader and reading from that reader to a buffer.
	//
	// If the connection is closed ErrNotConnected is returned.
	ReadMessage() (messageType int, message []byte, err error)

	// WriteMessage is a helper method for getting a writer using NextWriter,
	// writing the message and closing the writer.
	//
	// If the connection is closed ErrNotConnected is returned.
	WriteMessage(messageType int, data []byte) error

	// WriteJSON writes the JSON encoding of v to the connection.
	//
	// See the documentation for encoding/json Marshal for details about the
	// conversion of Go values to JSON.
	//
	// If the connection is closed ErrNotConnected is returned.
	WriteJSON(v interface{}) error

	// ReadJSON reads the next JSON-encoded message from the connection and stores
	// it in the value pointed to by v.
	//
	// See the documentation for the encoding/json Unmarshal function for details
	// about the conversion of JSON to a Go value.
	//
	// If the connection is closed ErrNotConnected is returned.
	ReadJSON(v interface{}) error

	// Dial creates a new client connection by calling DialContext with a background context.
	Dial() error

	// DialContext creates a new client connection.
	DialContext(ctx context.Context) error

	// GetURL returns connection url.
	GetURL() string

	// GetHTTPResponse returns the http response from the handshake.
	// Useful when WebSocket handshake fails,
	// so that callers can handle redirects, authentication, etc.
	GetHTTPResponse() *http.Response

	// IsConnected returns true if the websocket client is connected to the server.
	IsConnected() bool
}

func New

func New(url string, requestHeader http.Header, options ...Option) (RecConn, error)

New creates new Reconnecting Websocket connection The `url` parameter specifies the host and request URI. Use `requestHeader` to specify the origin (Origin), subprotocols (Sec-WebSocket-Protocol) and cookies (Cookie). Use GetHTTPResponse() method for the response.Header to get the selected subprotocol (Sec-WebSocket-Protocol) and cookies (Set-Cookie).