websocket

Documentation

Index

• Variables
• type NotificationType
  • func (n NotificationType) String() string
• type WSClient
  • func NewWebsocketClient(w http.ResponseWriter, r *http.Request, notificationMgr *WSNotificationManager) (*WSClient, error)
  • func (c *WSClient) Disconnect()
  • func (c *WSClient) Disconnected() bool
  • func (c *WSClient) QueueNotification(marshalledJSON []byte) error
  • func (c *WSClient) SendMessage(marshalledJSON []byte, doneChan chan bool)
  • func (c *WSClient) Start()
  • func (c *WSClient) WaitForShutdown()
• type WSNotificationManager
  • func NewWsNotificationManager(maxNumWebsockets int, maxNumConcurrentReqs int, chain *protocol.Chain, ...) *WSNotificationManager
  • func (m *WSNotificationManager) AddClient(wsc *WSClient)
  • func (m *WSNotificationManager) IsMaxConnect() bool
  • func (m *WSNotificationManager) NotifyBlockConnected(block *types.Block)
  • func (m *WSNotificationManager) NotifyBlockDisconnected(block *types.Block)
  • func (m *WSNotificationManager) NumClients() (n int)
  • func (m *WSNotificationManager) RegisterBlockUpdates(wsc *WSClient)
  • func (m *WSNotificationManager) RegisterNewMempoolTxsUpdates(wsc *WSClient)
  • func (m *WSNotificationManager) RemoveClient(wsc *WSClient)
  • func (m *WSNotificationManager) Shutdown()
  • func (m *WSNotificationManager) Start() error
  • func (m *WSNotificationManager) UnregisterBlockUpdates(wsc *WSClient)
  • func (m *WSNotificationManager) UnregisterNewMempoolTxsUpdates(wsc *WSClient)
  • func (m *WSNotificationManager) WaitForShutdown()
• type WSRequest
  • func NewWSRequest(topic string) *WSRequest
• type WSResponse
  • func NewWSResponse(notificationType string, data interface{}, err error) *WSResponse

Variables

var (
	// ErrWSParse means a request parsing error
	ErrWSParse = errors.New("Websocket request parsing error")
	// ErrWSInternal means service handling errors
	ErrWSInternal = errors.New("Websocket Internal error")
	// ErrWSClientQuit means the websocket client is disconnected
	ErrWSClientQuit = errors.New("Websocket client quit")
)

Types

type NotificationType

type NotificationType int

NotificationType represents the type of a notification message.

const (
	// NTBlockConnected indicates the associated block was connected to the main chain.
	NTRawBlockConnected NotificationType = iota
	// NTBlockDisconnected indicates the associated block was disconnected  from the main chain.
	NTRawBlockDisconnected
	NTNewTransaction
	NTRequestStatus
)

Constants for the type of a notification message.

func (NotificationType) String

func (n NotificationType) String() string

String returns the NotificationType in human-readable form.

type WSClient

type WSClient struct {
	sync.Mutex
	// contains filtered or unexported fields
}

WSClient provides an abstraction for handling a websocket client. The overall data flow is split into 3 main goroutines, a possible 4th goroutine for long-running operations (only started if request is made), and a websocket manager which is used to allow things such as broadcasting requested notifications to all connected websocket clients. Inbound messages are read via the inHandler goroutine and generally dispatched to their own handler. However, certain potentially long-running operations such as rescans, are sent to the asyncHander goroutine and are limited to one at a time. There are two outbound message types - one for responding to client requests and another for async notifications. Responses to client requests use SendMessage which employs a buffered channel thereby limiting the number of outstanding requests that can be made. Notifications are sent via QueueNotification which implements a queue via notificationQueueHandler to ensure sending notifications from other subsystems can't block. Ultimately, all messages are sent via the outHandler.

func NewWebsocketClient

func NewWebsocketClient(w http.ResponseWriter, r *http.Request, notificationMgr *WSNotificationManager) (*WSClient, error)

NewWebsocketClient means to create a new object to the connected websocket client

func (*WSClient) Disconnect

func (c *WSClient) Disconnect()

Disconnect disconnects the websocket client.

func (*WSClient) Disconnected

func (c *WSClient) Disconnected() bool

Disconnected returns whether or not the websocket client is disconnected.

func (*WSClient) QueueNotification

func (c *WSClient) QueueNotification(marshalledJSON []byte) error

QueueNotification queues the passed notification to be sent to the websocket client.

func (*WSClient) SendMessage

func (c *WSClient) SendMessage(marshalledJSON []byte, doneChan chan bool)

SendMessage sends the passed json to the websocket client. It is backed by a buffered channel, so it will not block until the send channel is full. Note however that QueueNotification must be used for sending async notifications instead of the this function. This approach allows a limit to the number of outstanding requests a client can make without preventing or blocking on async notifications.

func (*WSClient) Start

func (c *WSClient) Start()

Start begins processing input and output messages.

func (*WSClient) WaitForShutdown

func (c *WSClient) WaitForShutdown()

WaitForShutdown blocks until the websocket client goroutines are stopped and the connection is closed.

type WSNotificationManager

type WSNotificationManager struct {
	MaxNumWebsockets int
	// contains filtered or unexported fields
}

WSNotificationManager is a connection and notification manager used for websockets. It allows websocket clients to register for notifications they are interested in. When an event happens elsewhere in the code such as transactions being added to the memory pool or block connects/disconnects, the notification manager is provided with the relevant details needed to figure out which websocket clients need to be notified based on what they have registered for and notifies them accordingly. It is also used to keep track of all connected websocket clients.

func NewWsNotificationManager

func NewWsNotificationManager(maxNumWebsockets int, maxNumConcurrentReqs int, chain *protocol.Chain, dispatcher *event.Dispatcher) *WSNotificationManager

NewWsNotificationManager returns a new notification manager ready for use. See WSNotificationManager for more details.

func (*WSNotificationManager) AddClient

func (m *WSNotificationManager) AddClient(wsc *WSClient)

AddClient adds the passed websocket client to the notification manager.

func (*WSNotificationManager) IsMaxConnect

func (m *WSNotificationManager) IsMaxConnect() bool

IsMaxConnect returns whether the maximum connection is exceeded

func (*WSNotificationManager) NotifyBlockConnected

func (m *WSNotificationManager) NotifyBlockConnected(block *types.Block)

NotifyBlockConnected passes a block newly-connected to the best chain to the notification manager for block and transaction notification processing.

func (*WSNotificationManager) NotifyBlockDisconnected

func (m *WSNotificationManager) NotifyBlockDisconnected(block *types.Block)

NotifyBlockDisconnected passes a block disconnected from the best chain to the notification manager for block notification processing.

func (*WSNotificationManager) NumClients

func (m *WSNotificationManager) NumClients() (n int)

NumClients returns the number of clients actively being served.

func (*WSNotificationManager) RegisterBlockUpdates

func (m *WSNotificationManager) RegisterBlockUpdates(wsc *WSClient)

RegisterBlockUpdates requests block update notifications to the passed websocket client.

func (*WSNotificationManager) RegisterNewMempoolTxsUpdates

func (m *WSNotificationManager) RegisterNewMempoolTxsUpdates(wsc *WSClient)

RegisterNewMempoolTxsUpdates requests notifications to the passed websocket client when new transactions are added to the memory pool.

func (*WSNotificationManager) RemoveClient

func (m *WSNotificationManager) RemoveClient(wsc *WSClient)

RemoveClient removes the passed websocket client and all notifications registered for it.

func (*WSNotificationManager) Shutdown

func (m *WSNotificationManager) Shutdown()

Shutdown shuts down the manager, stopping the notification queue and notification handler goroutines.

func (*WSNotificationManager) Start

func (m *WSNotificationManager) Start() error

Start starts the goroutines required for the manager to queue and process websocket client notifications.

func (*WSNotificationManager) UnregisterBlockUpdates

func (m *WSNotificationManager) UnregisterBlockUpdates(wsc *WSClient)

UnregisterBlockUpdates removes block update notifications for the passed websocket client.

func (*WSNotificationManager) UnregisterNewMempoolTxsUpdates

func (m *WSNotificationManager) UnregisterNewMempoolTxsUpdates(wsc *WSClient)

UnregisterNewMempoolTxsUpdates removes notifications to the passed websocket client when new transaction are added to the memory pool.

func (*WSNotificationManager) WaitForShutdown

func (m *WSNotificationManager) WaitForShutdown()

WaitForShutdown blocks until all notification manager goroutines have finished.

type WSRequest

type WSRequest struct {
	Topic string `json:"topic"`
}

WSRequest means the data structure of the request

func NewWSRequest

func NewWSRequest(topic string) *WSRequest

NewWSRequest creates a request data object

type WSResponse

type WSResponse struct {
	NotificationType string      `json:"notification_type"`
	Data             interface{} `json:"data"`
	ErrorDetail      string      `json:"error_detail,omitempty"`
}

WSResponse means the returned data structure

func NewWSResponse

func NewWSResponse(notificationType string, data interface{}, err error) *WSResponse

NewWSResponse creates a return data object