webgockets

README

Webgockets

A websocket client implementation in go.

Example

A simple echo example

c, err := NewClient("ws://example.com")
if err != nil {
    // Handle error.
}

if err := c.Connect(); err != nil {
    // Handle error.
}

for {
    var closeErr *webgockets.ErrClose
    bs, err := c.Read()
    if errors.As(err, &closeErr) { // Connection closed.
        break
    } else if err != nil {
        // Handle error.
    }

    if _, err := c.Write(bs); err != nil && errors.Is(err, io.EOF) { // Connection closed.
        break
    } else if err != nil {
        // Handle error.
    }
}

Autobahn Testsuite

This implementation passes all basic cases in the test suite (except for UTF-8 checks, I deemed that unnecessary strict). The report is here

Documentation

Index

• Variables
• func ReadJSON[T any](ctx context.Context, client *Client) (*T, error)
• type Client
  • func NewClient(wsURL string) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Connect() error
  • func (c *Client) Read(ctx context.Context) ([]byte, error)
  • func (c *Client) ReadString(ctx context.Context) (string, error)
  • func (c *Client) Write(bs []byte) (int, error)
  • func (c *Client) WriteBinary(bs []byte) (int, error)
  • func (c *Client) WriteJSON(jsonData any) (int, error)
  • func (c *Client) WriteString(str string) (int, error)
• type ErrClose
  • func (e *ErrClose) Error() string
• type OpCode
  • func (o OpCode) String() string

Variables

var ErrInvalidJSON = errors.New("invalid json")

Functions

func ReadJSON

func ReadJSON[T any](ctx context.Context, client *Client) (*T, error)

ReadJSON is a convenience function to unmarshal a client read into a json struct. Ideally, this should be a method to the client, but due to go limitations with generic methods, we can't do that for now.

Types

type Client

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

func NewClient

func NewClient(wsURL string) (*Client, error)

NewClient validates the wsURL and creates a new Client.

func (*Client) Close

func (c *Client) Close() error

func (*Client) Connect

func (c *Client) Connect() error

Connect handshakes and starts receiving messages.

func (*Client) Read

func (c *Client) Read(ctx context.Context) ([]byte, error)

Read reads a non-fragmented frame, or concatenates the payload of multiple fragmented frames.

func (*Client) ReadString

func (c *Client) ReadString(ctx context.Context) (string, error)

func (*Client) Write

func (c *Client) Write(bs []byte) (int, error)

Write writes a text frame.

func (*Client) WriteBinary

func (c *Client) WriteBinary(bs []byte) (int, error)

WriteBinary writes a binary frame

func (*Client) WriteJSON

func (c *Client) WriteJSON(jsonData any) (int, error)

WriteJSON writes a text frame with marshaled bytes from the given json struct.

func (*Client) WriteString

func (c *Client) WriteString(str string) (int, error)

type ErrClose

type ErrClose struct {
	Code    uint16
	Payload string
}

func (*ErrClose) Error

func (e *ErrClose) Error() string

type OpCode

type OpCode int

const (
	OpcodeContinuationFrame OpCode = iota
	OpcodeTextFrame
	OpcodeBinaryFrame
	OpcodeReservedNonControl1
	OpcodeReservedNonControl2
	OpcodeReservedNonControl3
	OpcodeReservedNonControl4
	OpcodeReservedNonControl5
	OpcodeConnectionClose
	OpcodePing
	OpcodePong
	OpcodeReservedControl1
	OpcodeReservedControl2
	OpcodeReservedControl3
	OpcodeReservedControl4
	OpcodeReservedControl5
)

func (OpCode) String

func (o OpCode) String() string