gows

README

gows

Minimal RFC compliant WebSocket Version 13 implementation in Pure Go with zero dependencies and with net/http compatibility.

Features

• RFC 6455 compliant WebSocket 13 implementation
• RFC 7602 compliant WebSocket Compression Extensions implementation

Usage

gows.Client

import "github.com/cookiengineer/gows"
import "log"
import "time"

logger := log.New(os.Stdout, "[client] ", log.LstdFlags)
client, err0 := gows.NewClient("ws://localhost:8080")

if err0 == nil {

    err1 := client.Connect()

    if err1 == nil {

        time.Sleep(100 * time.Millisecond)
        client.Socket.Send([]byte("Hello, world!"))

        time.Sleep(1 * time.Second)
        client.Socket.Close(gows.StatusGoingAway, "Goodbye!")

    } else {
        logger.Fatal(err1)
    }

} else {
    logger.Fatal(err0)
}

gows.Server

import "github.com/cookiengineer/gows"
import "log"

logger := log.New(os.Stdout, "[server] ", log.LstdFlags)
server := &gows.Server{
    Addr:    ":8080",
    Handler: func(websocket *gows.WebSocket) {

        logger.Print("Client connected!")

        websocket.OnMessage = func(message []byte) {
            logger.Printf("Received message: %s", message)
        }

        websocket.OnClose = func() {
            logger.Print("Client disconnected!")
        }

    },
    TLSConfig: nil,
    ErrorLog:  logger,
}

server.Listen()

Examples

Check out the examples folder for further API usage examples.

• simple is a simple client and server.
• permessage-deflate is a client and server that uses a websocket extension.
• chatserver is a fully integrated web chat server.

License

This library is licensed under the X11/MIT License

Documentation

Index

• Variables
• type Client
  • func NewClient(raw_url string) (*Client, error)
  • func (client *Client) Connect() error
• type Extension
• type Handler
• type Operation
  • func (operation Operation) IsControl() bool
  • func (operation Operation) IsValid() bool
• type Packet
  • func ParsePacket(frame []byte) (Packet, error)
  • func (packet *Packet) Marshal() ([]byte, error)
  • func (packet *Packet) Unmarshal(frame []byte) error
• type Protocols
  • func (protocols Protocols) Negotiate(requested string) string
• type Server
  • func (server *Server) AddSocket(websocket *WebSocket)
  • func (server *Server) Close() error
  • func (server *Server) Listen() error
  • func (server *Server) RegisterOnShutdown(callback func())
  • func (server *Server) RemoveSocket(websocket *WebSocket)
  • func (server *Server) Serve(listener net.Listener) error
  • func (server *Server) ServeTLS(listener net.Listener, cert_file string, key_file string) error
  • func (server *Server) Shutdown(ctx context.Context) error
  • func (server *Server) Upgrade(response http.ResponseWriter, request *http.Request) (*WebSocket, error)
• type SocketType
• type Status
• type WebSocket
  • func NewWebSocket(connection net.Conn, server *Server) *WebSocket
  • func (websocket *WebSocket) Close(status Status, reason string)
  • func (websocket *WebSocket) Destroy()
  • func (websocket *WebSocket) Init()
  • func (websocket *WebSocket) Send(data []byte) error
  • func (websocket *WebSocket) SendBinary(data []byte) error
  • func (websocket *WebSocket) SendPacket(packet Packet) error

Variables

var (
	ErrPacketIncomplete             = errors.New("websocket: incomplete packet")
	ErrPacketTooLarge               = errors.New("websocket: packet too large")
	ErrPacketControlFrameFragmented = errors.New("websocket: fragmented control frame")
	ErrPacketControlFrameTooLarge   = errors.New("websocket: control frame too large")
	ErrPacketInvalidOperation       = errors.New("websocket: invalid opcode")
	ErrPacketReservedBits           = errors.New("websocket: reserved bits set without extension")
	ErrServerClosed                 = errors.New("websocket: server closed")
	ErrExtensionNegotiationFailed   = errors.New("websocket: extension negotiation failed")
)

Types

type Client

type Client struct {
	Socket    *WebSocket
	TLSConfig *tls.Config
	URL       *net_url.URL

	Extensions []Extension
	// contains filtered or unexported fields
}

func NewClient

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

func (*Client) Connect

func (client *Client) Connect() error

type Extension

type Extension interface {

	// Name returns the extension identifier (e.g., "permessage-deflate").
	Name() string

	// Parameters returns the extension's parameters to include in the
	// client's Sec-WebSocket-Extensions offer header.
	// Returns nil if the extension should not be offered.
	Parameters() map[string]string

	// Negotiate is called by the server with the client's offered parameters.
	// Returns agreed parameters and true if accepted, or nil and false if declined.
	Negotiate(offer map[string]string) (agreed map[string]string, accepted bool)

	// Accept is called by the client with the server's response parameters.
	// Returns true if the client accepts the server's configuration.
	Accept(response map[string]string) bool

	// Compress transforms an outgoing data message payload before framing.
	// Only called for non-control frames when extensions are active.
	Compress(payload []byte) ([]byte, error)

	// Decompress transforms an incoming data message payload after reassembly.
	// Only called for data messages where the first frame had RSV1 set.
	Decompress(payload []byte) ([]byte, error)
}

type Handler

type Handler func(*WebSocket)

type Operation

type Operation byte

const (
	OperationContinue Operation = 0x00
	OperationText     Operation = 0x01
	OperationBinary   Operation = 0x02
	// Reserved Control Frames: 0x03-0x07
	OperationClose Operation = 0x08
	OperationPing  Operation = 0x09
	OperationPong  Operation = 0x0a
)

func (Operation) IsControl

func (operation Operation) IsControl() bool

func (Operation) IsValid

func (operation Operation) IsValid() bool

type Packet

type Packet struct {
	Operation Operation  `json:"operation"`
	Type      SocketType `json:"type"`
	Mask      []byte     `json:"mask"`
	Payload   []byte     `json:"payload"`
	Reserved  [3]bool    `json:"reserved"`
	Final     bool       `json:"final"`
}

func ParsePacket

func ParsePacket(frame []byte) (Packet, error)

func (*Packet) Marshal

func (packet *Packet) Marshal() ([]byte, error)

func (*Packet) Unmarshal

func (packet *Packet) Unmarshal(frame []byte) error

type Protocols

type Protocols []string

func (Protocols) Negotiate

func (protocols Protocols) Negotiate(requested string) string

type Server

type Server struct {
	Addr         string
	Handler      Handler
	TLSConfig    *tls.Config
	TLSNextProto map[string]func(*Server, *tls.Conn, Handler)
	ErrorLog     *log.Logger
	BaseContext  func(net.Listener) context.Context
	ConnContext  func(context.Context, net.Conn) context.Context
	Protocols    *Protocols
	Extensions   []Extension
	Sockets      []*WebSocket
	// contains filtered or unexported fields
}

func (*Server) AddSocket

func (server *Server) AddSocket(websocket *WebSocket)

func (*Server) Close

func (server *Server) Close() error

func (*Server) Listen

func (server *Server) Listen() error

func (*Server) RegisterOnShutdown

func (server *Server) RegisterOnShutdown(callback func())

func (*Server) RemoveSocket

func (server *Server) RemoveSocket(websocket *WebSocket)

func (*Server) Serve

func (server *Server) Serve(listener net.Listener) error

func (*Server) ServeTLS

func (server *Server) ServeTLS(listener net.Listener, cert_file string, key_file string) error

func (*Server) Shutdown

func (server *Server) Shutdown(ctx context.Context) error

func (*Server) Upgrade

func (server *Server) Upgrade(response http.ResponseWriter, request *http.Request) (*WebSocket, error)

type SocketType

type SocketType string

const (
	SocketTypeClient SocketType = "client"
	SocketTypeServer SocketType = "server"
)

type Status

type Status uint16

const (
	StatusNormalClosure     Status = 1000
	StatusGoingAway         Status = 1001
	StatusProtocolError     Status = 1002
	StatusUnsupportedData   Status = 1003
	StatusNoStatusReceived  Status = 1005
	StatusAbnormalClosure   Status = 1006
	StatusInvalidPayload    Status = 1007
	StatusPolicyViolation   Status = 1008
	StatusMessageTooBig     Status = 1009
	StatusExtensionRequired Status = 1010
	StatusInternalError     Status = 1011
)

type WebSocket

type WebSocket struct {
	Connection net.Conn     `json:"connection"`
	Frames     []Packet     `json:"frames"`
	Type       SocketType   `json:"type"`
	Server     *Server      `json:"server"`
	Extensions []Extension  `json:"-"`
	OnMessage  func([]byte) `json:"-"`
	OnClose    func()       `json:"-"`
	// contains filtered or unexported fields
}

func NewWebSocket

func NewWebSocket(connection net.Conn, server *Server) *WebSocket

func (*WebSocket) Close

func (websocket *WebSocket) Close(status Status, reason string)

func (*WebSocket) Destroy

func (websocket *WebSocket) Destroy()

func (*WebSocket) Init

func (websocket *WebSocket) Init()

func (*WebSocket) Send

func (websocket *WebSocket) Send(data []byte) error

func (*WebSocket) SendBinary

func (websocket *WebSocket) SendBinary(data []byte) error

func (*WebSocket) SendPacket

func (websocket *WebSocket) SendPacket(packet Packet) error