websocket

README

GWS (Go WebSocket)

author: xdrm-brackets

Websocket implementation in go. It features a server as well as a client.

Key objectives

objective	my definition
fast	response time less than 1ms at least
reliable	gracefully handle usage/network/... errors
secure	add available cryptography (stream)
compatible	respect RFC-6455 as well as actual browser implementations
generic	use golang implicit interfaces to make the code reusable for all (most) cases

Documentation

Index

• Constants
• type Client
• type Controller
• type ControllerFunc
• type ControllerSet
  • func (s *ControllerSet) Match(uri string) (*Controller, [][]string)
• type Message
  • func (m Message) Send(writer io.Writer) error
• type MessageError
• type MessageType
• type Server
  • func CreateServer(host string, port uint16) *Server
  • func (s *Server) Bind(uriStr string, f ControllerFunc) error
  • func (s *Server) BindDefault(f ControllerFunc)
  • func (s *Server) Launch() error

Constants

const (
	// ErrUnmaskedFrame error
	ErrUnmaskedFrame = constErr("Received unmasked frame")
	// ErrTooLongControlFrame error
	ErrTooLongControlFrame = constErr("Received a control frame that is fragmented or too long")
	// ErrInvalidFragment error
	ErrInvalidFragment = constErr("Received invalid fragmentation")
	// ErrUnexpectedContinuation error
	ErrUnexpectedContinuation = constErr("Received unexpected continuation frame")
	// ErrInvalidSize error
	ErrInvalidSize = constErr("Received invalid payload size")
	// ErrInvalidPayload error
	ErrInvalidPayload = constErr("Received invalid utf8 payload")
	// ErrInvalidCloseStatus error
	ErrInvalidCloseStatus = constErr("Received invalid close status")
	// ErrInvalidOpCode error
	ErrInvalidOpCode = constErr("Received invalid OpCode")
	// ErrReservedBits error
	ErrReservedBits = constErr("Received reserved bits")
	// ErrCloseFrame error
	ErrCloseFrame = constErr("Received close Frame")
)

Types

type Client

type Client struct {
	Protocol  string      // choosen protocol (Sec-WebSocket-Protocol)
	Arguments [][]string  // URI parameters, index 0 is full URI, then matching groups
	Store     interface{} // store (for client implementation-specific data)
}

Client contains available information about a client

type Controller

type Controller struct {
	URI *uri.Scheme    // uri scheme
	Fun ControllerFunc // controller function
}

Controller is a websocket controller

type ControllerFunc

type ControllerFunc func(*Client, <-chan Message, chan<- Message, chan<- Message)

ControllerFunc is a websocket controller callback function

type ControllerSet

type ControllerSet struct {
	Def *Controller   // default controller
	URI []*Controller // uri controllers
}

ControllerSet is set of controllers

func (*ControllerSet) Match

func (s *ControllerSet) Match(uri string) (*Controller, [][]string)

Match finds a controller for a given URI also it returns the matching string patterns

type Message

type Message struct {
	Final bool
	Type  MessageType
	Size  uint
	Data  []byte
}

Message is a websocket message

func (Message) Send

func (m Message) Send(writer io.Writer) error

Send sends a frame over a socket

type MessageError

type MessageError uint16

MessageError lists websocket close statuses

const (
	// None used when there is no error
	None MessageError = 0
	// Normal error
	Normal MessageError = 1000
	// GoingAway error
	GoingAway MessageError = 1001
	// ProtocolError error
	ProtocolError MessageError = 1002
	// UnacceptableOpCode error
	UnacceptableOpCode MessageError = 1003
	// InvalidPayload error
	InvalidPayload MessageError = 1007 // utf8
	// MessageTooLarge error
	MessageTooLarge MessageError = 1009
)

type MessageType

type MessageType byte

MessageType lists websocket message types

const (
	// Continuation message type
	Continuation MessageType = 0x00
	// Text message type
	Text MessageType = 0x01
	// Binary message type
	Binary MessageType = 0x02
	// Close message type
	Close MessageType = 0x08
	// Ping message type
	Ping MessageType = 0x09
	// Pong message type
	Pong MessageType = 0x0a
)

type Server

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

Server is a websocket server

func CreateServer

func CreateServer(host string, port uint16) *Server

CreateServer for a specific HOST and PORT

func (*Server) Bind

func (s *Server) Bind(uriStr string, f ControllerFunc) error

Bind a controller to an URI scheme

func (*Server) BindDefault

func (s *Server) BindDefault(f ControllerFunc)

BindDefault binds a default controller it will be called if the URI does not match another controller

func (*Server) Launch

func (s *Server) Launch() error

Launch the websocket server