gows

README

gows

A basic reconnecting websocket library that supports:

• Query parameters
• Queueing during reconnects
• Automatic heartbeats
• Self-signed certificates for localhost connections

Usage

Usage is as simple as configuring and connecting:

import (
    "github.com/miratronix/gows"
	"github.com/miratronix/logpher"
)

// Initialize the websocket
ws := gows.New(&gows.Configuration{
	URL:                       "ws://some.url",         // The URL to connect to
	Query:                     "query_param=something", // Query parameters to add to the above URL
	Logger:                    logpher.NewLogger("ws"), // The logger for the websocket
	ConnectionRetries:         5,                       // The number of connection retries on initial connection
	ConnectionRetryFactor:     2,                       // The exponential retry factor
	ConnectionRetryTimeoutMin: 1 * time.Second,         // The minimum timeout for connection retries
	ConnectionRetryTimeoutMax: 5 * time.Second,         // The maximum timeout for connection retries
	ConnectionRetryRandomize:  false,                   // Whether to apply randomness to the timeout interval
	PingInterval:              30 * time.Second,        // The interval to send pings at
	WriteTimeout:              5 * time.Second,         // The timeout for write operations
	ReadTimeout:               35 * time.Second,        // The timeout for read operations. Should be longer than the ping interval
	InsecureLocalhost:         false,                   // Whether to skip certificate validation for localhost connections
	RetryInitialConnection:    false,                   // Whether to apply retry logic to the initial connection attempt
})

// Attach handlers for various events
ws.OnConnected(func() {})
ws.OnMessage(func(msg []byte) {})
ws.OnDisconnected(func() {})

// Will return an error if the initial connection attempt fails ConnectionRetries times
err := ws.Connect()

// Returns immediately, but doesn't attempt to send until the socket is connected
ws.Send([]byte("Hello world!"))

// Queues outgoing packets (without making Send block)
ws.BlockSend()

// Unblocks outgoing packets and flushes any queued packets
ws.UnblockSend()

// Determines if the socket is currently connected (false during reconnects)
connected := ws.IsConnected()

// Disconnects the socket
err = ws.Disconnect()

Documentation

Index

• type Configuration
• type Websocket
  • func New(configuration *Configuration) *Websocket
  • func (ws *Websocket) BlockSend()
  • func (ws *Websocket) Connect() error
  • func (ws *Websocket) Disconnect()
  • func (ws *Websocket) IsConnected() bool
  • func (ws *Websocket) OnConnected(handler func())
  • func (ws *Websocket) OnDisconnected(handler func())
  • func (ws *Websocket) OnMessage(handler func([]byte))
  • func (ws *Websocket) Send(msg []byte)
  • func (ws *Websocket) UnblockSend()

Types

type Configuration

type Configuration struct {
	URL                       string
	Query                     string
	Logger                    *logpher.Logger
	ConnectionRetries         int
	ConnectionRetryFactor     float64
	ConnectionRetryTimeoutMin time.Duration
	ConnectionRetryTimeoutMax time.Duration
	ConnectionRetryRandomize  bool
	PingInterval              time.Duration
	WriteTimeout              time.Duration
	ReadTimeout               time.Duration
	InsecureLocalhost         bool
	RetryInitialConnection    bool
	// contains filtered or unexported fields
}

Configuration defines the options structure for the websocket connection

type Websocket

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

Websocket defines a simple websocket structure

func New

func New(configuration *Configuration) *Websocket

New constructs a new websocket object

func (*Websocket) BlockSend

func (ws *Websocket) BlockSend()

BlockSend blocks message sending until UnblockSend() is called

func (*Websocket) Connect

func (ws *Websocket) Connect() error

Connect connects the websocket

func (*Websocket) Disconnect

func (ws *Websocket) Disconnect()

Disconnect disconnects the websocket

func (*Websocket) IsConnected

func (ws *Websocket) IsConnected() bool

IsConnected determines if the socket is currently connected

func (*Websocket) OnConnected

func (ws *Websocket) OnConnected(handler func())

OnConnected sets the onConnected handler

func (*Websocket) OnDisconnected

func (ws *Websocket) OnDisconnected(handler func())

OnDisconnected sets the onDisconnected handler

func (*Websocket) OnMessage

func (ws *Websocket) OnMessage(handler func([]byte))

OnMessage sets the onMessage handler

func (*Websocket) Send

func (ws *Websocket) Send(msg []byte)

Send sends a binary message with the provided body

func (*Websocket) UnblockSend

func (ws *Websocket) UnblockSend()

UnblockSend stops blocking message sending