README

WSC

codecov

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
}
Expand ▾ Collapse ▴

Documentation

Overview

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

    Index

    Constants

    This section is empty.

    Variables

    View Source
    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.

      Functions

      This section is empty.

      Types

      type Config

      type Config struct {
      	WriteWait         time.Duration
      	PongWait          time.Duration
      	PingPeriod        time.Duration
      	TLSConfig         *tls.Config
      	ReadBufferSize    int
      	ReadChanSize      int
      	WriteBufferSize   int
      	WriteChanSize     int
      	EnableCompression bool
      	Headers           http.Header
      }

        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.