wsc

README

WSC

WSC (WebSocket Channel) is a library that can be used to manage github.com/gorilla/websocket using channels.

It provides 2 main functions:

• func Connect(ctx context.Context, url string, config Config) (Websocket, *http.Response, error)
• func Accept(ctx context.Context, conn WSConnection, config Config) (Websocket, error)

The interface WSConnection is used to interract with the websocket:

// Websocket is the interface of channel based websocket.
type Websocket interface {

  // Reads returns a channel where the incoming messages are published.
  // If nothing pumps the Read() while it is full, new messages will be
  // discarded.
  //
  // You can configure the size of the read chan in Config.
  // The default is 64 messages.
  Read() chan []byte

  // Write writes the given []byte in to the websocket.
  // If the other side of the websocket cannot get all messages
  // while the internal write channel is full, new messages will
  // be discarded.
  //
  // You can configure the size of the write chan in Config.
  // The default is 64 messages.
  Write([]byte)

  // Done returns a channel that will return when the connection
  // is closed.
  //
  // The content will be nil for clean disconnection or
  // the error that caused the disconnection. If nothing pumps the
  // Done() channel, the error will be discarded.
  Done() chan error

  // Close closes the websocket.
  //
  // Closing the websocket a second time has no effect.
  // A closed Websocket cannot be reused.
  Close(code int)

  // Error returns a channel that will return errors like
  // read or write discards and other errors that are not
  // terminating the connection.
  //
  // If nothing pumps the Error() channel, the error will be discarded.
  Error() chan error
}

Documentation

Overview

Package wsc provides an idiomatic way to deal with websockets using channels.

Index

• Variables
• type Config
• type MockWebsocket
  • func NewMockWebsocket(ctx context.Context) MockWebsocket
• type WSConnection
• type Websocket
  • func Accept(ctx context.Context, conn WSConnection, config Config) (Websocket, error)
  • func Connect(ctx context.Context, url string, config Config) (Websocket, *http.Response, error)

Variables

var (
	ErrWriteMessageDiscarded = fmt.Errorf("write chan full: one or more messages has not been sent")
	ErrReadMessageDiscarded  = fmt.Errorf("read chan full: one or more messages has not been received")
)

various error messages.

Types

type Config

type Config struct {
	TLSConfig          *tls.Config
	Headers            http.Header
	NetDialContextFunc func(ctx context.Context, network, addr string) (net.Conn, error)
	WriteWait          time.Duration
	PongWait           time.Duration
	PingPeriod         time.Duration
	ReadBufferSize     int
	ReadChanSize       int
	WriteBufferSize    int
	WriteChanSize      int
	EnableCompression  bool
}

Config contains configuration for the webbsocket.

type MockWebsocket

type MockWebsocket interface {
	NextRead(data []byte)
	LastWrite() chan []byte
	NextDone(err error)

	Websocket
}

A MockWebsocket is a utility to write unit tests on websockets.

func NewMockWebsocket

func NewMockWebsocket(ctx context.Context) MockWebsocket

NewMockWebsocket returns a mocked Websocket that can be used in unit tests.

type WSConnection

type WSConnection interface {
	SetReadDeadline(time.Time) error
	SetWriteDeadline(time.Time) error
	SetCloseHandler(func(code int, text string) error)
	SetPongHandler(func(string) error)
	ReadMessage() (int, []byte, error)
	WriteMessage(int, []byte) error
	WriteControl(int, []byte, time.Time) error
	Close() error
}

WSConnection is the interface that must be implemented as a websocket. github.com/gorilla/websocket implements this interface.

type Websocket

type Websocket interface {

	// Reads returns a channel where the incoming messages are published.
	// If nothing pumps the Read() while it is full, new messages will be
	// discarded.
	//
	// You can configure the size of the read chan in Config.
	// The default is 64 messages.
	Read() chan []byte

	// Write writes the given []byte in to the websocket.
	// If the other side of the websocket cannot get all messages
	// while the internal write channel is full, new messages will
	// be discarded.
	//
	// You can configure the size of the write chan in Config.
	// The default is 64 messages.
	Write([]byte)

	// Done returns a channel that will return when the connection
	// is closed.
	//
	// The content will be nil for clean disconnection or
	// the error that caused the disconnection. If nothing pumps the
	// Done() channel, the error will be discarded.
	Done() chan error

	// Close closes the websocket.
	//
	// Closing the websocket a second time has no effect.
	// A closed Websocket cannot be reused.
	Close(code int)

	// Error returns a channel that will return errors like
	// read or write discards and other errors that are not
	// terminating the connection.
	//
	// If nothing pumps the Error() channel, the error will be discarded.
	Error() chan error
}

Websocket is the interface of channel based websocket.

func Accept

func Accept(ctx context.Context, conn WSConnection, config Config) (Websocket, error)

Accept handles an already connect *websocket.Conn and returns a Websocket.

func Connect

func Connect(ctx context.Context, url string, config Config) (Websocket, *http.Response, error)

Connect connects to the url and returns a Websocket.