websocket

package module
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 5, 2021 License: MIT Imports: 20 Imported by: 7

README

websocket

WebSocket library for fasthttp.

Checkout examples to inspire yourself.

Why another WebSocket package?

Other WebSocket packages don't allow concurrent Read/Write operations and does not provide low level access to WebSocket packet crafting.

Following the fasthttp philosophy this library tries to take as much advantage of the Golang's multi-threaded model as possible, while keeping your code concurrently safe.

To see an example of what this package CAN do that others DONT checkout the broadcast example.

websocket vs gorilla vs nhooyr vs gobwas

Features websocket Gorilla Nhooyr gowabs
Concurrent R/W Yes No No. Only writes No
Passes Autobahn Test Suite Mostly Yes Yes Mostly
Receive fragmented message Yes Yes Yes Yes
Send close message Yes Yes Yes Yes
Send pings and receive pongs Yes Yes Yes Yes
Get the type of a received data message Yes Yes Yes Yes
Compression Extensions No Experimental Yes No (?)
Read message using io.Reader No Yes No No (?)
Write message using io.WriteCloser No Yes No No (?)

Stress tests

The following stress test were performed without timeouts:

Executing tcpkali --ws -c 100 -m 'hello world!!13212312!' -r 10k localhost:8081 the tests shows the following:

Websocket:

Total data sent:     267.7 MiB (280678466 bytes)
Total data received: 229.5 MiB (240626600 bytes)
Bandwidth per channel: 4.167⇅ Mbps (520.9 kBps)
Aggregate bandwidth: 192.357↓, 224.375↑ Mbps
Packet rate estimate: 247050.1↓, 61842.9↑ (1↓, 1↑ TCP MSS/op)
Test duration: 10.0075 s.

Gorilla:

Total data sent:     260.2 MiB (272886768 bytes)
Total data received: 109.3 MiB (114632982 bytes)
Bandwidth per channel: 3.097⇅ Mbps (387.1 kBps)
Aggregate bandwidth: 91.615↓, 218.092↑ Mbps
Packet rate estimate: 109755.3↓, 66807.4↑ (1↓, 1↑ TCP MSS/op)
Test duration: 10.01 s.

Nhooyr: (Don't know why is that low)

Total data sent:     224.3 MiB (235184096 bytes)
Total data received: 41.2 MiB (43209780 bytes)
Bandwidth per channel: 2.227⇅ Mbps (278.3 kBps)
Aggregate bandwidth: 34.559↓, 188.097↑ Mbps
Packet rate estimate: 88474.0↓, 55256.1↑ (1↓, 1↑ TCP MSS/op)
Test duration: 10.0027 s.

Gobwas:

Total data sent:     265.8 MiB (278718160 bytes)
Total data received: 117.8 MiB (123548959 bytes)
Bandwidth per channel: 3.218⇅ Mbps (402.2 kBps)
Aggregate bandwidth: 98.825↓, 222.942↑ Mbps
Packet rate estimate: 148231.6↓, 72106.1↑ (1↓, 1↑ TCP MSS/op)
Test duration: 10.0015 s.

The source files are in this folder.

Documentation

Index

Constants

View Source 
const (
	// StatusNone is used to let the peer know nothing happened.
	StatusNone StatusCode = 1000
	// StatusGoAway peer's error.
	StatusGoAway = 1001
	// StatusProtocolError problem with the peer's way to communicate.
	StatusProtocolError = 1002
	// StatusNotAcceptable when a request is not acceptable
	StatusNotAcceptable = 1003
	// StatusReserved when a reserved field have been used
	StatusReserved = 1004
	// StatusNotConsistent IDK
	StatusNotConsistent = 1007
	// StatusViolation a violation of the protocol happened
	StatusViolation = 1008
	// StatusTooBig payload bigger than expected
	StatusTooBig = 1009
	// StatuseExtensionsNeeded IDK
	StatuseExtensionsNeeded = 1010
	// StatusUnexpected IDK
	StatusUnexpected = 1011
)
View Source 
const DefaultPayloadSize = 1 << 20

DefaultPayloadSize defines the default payload size (when none was defined).

Variables

View Source 
var (
	// EOF represents an io.EOF error.
	EOF = io.EOF
)
View Source 
var (
	// ErrCannotUpgrade shows up when an error occurred when upgrading a connection.
	ErrCannotUpgrade = errors.New("cannot upgrade connection")
)

Functions

func ReleaseFrame 

func ReleaseFrame(fr *Frame)

ReleaseFrame puts fr Frame into the global pool.

func UpgradeAsClient 

func UpgradeAsClient(c net.Conn, url string, r *fasthttp.Request) error

UpgradeAsClient will upgrade the connection as a client

r can be nil.

Types

type Client 

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

Client ...

func ClientWithHeaders 

func ClientWithHeaders(c net.Conn, url string, req *fasthttp.Request) (*Client, error)

ClientWithHeaders returns a Conn using existing connection and sending personalized headers.

func Dial 

func Dial(url string) (*Client, error)

Dial establishes a websocket connection as client.

url parameter must follow WebSocket URL format i.e. ws://host:port/path

func DialTLS 

func DialTLS(url string, cnf *tls.Config) (*Client, error)

DialTLS establishes a websocket connection as client with the parsed tls.Config. The config will be used if the URL is wss:// like.

func DialWithHeaders 

func DialWithHeaders(url string, req *fasthttp.Request) (*Client, error)

DialWithHeaders establishes a websocket connection as client sending a personalized request.

func MakeClient 

func MakeClient(c net.Conn, url string) (*Client, error)

MakeClient returns Conn using existing connection.

url must be complete URL format i.e. http://localhost:8080/ws

func (*Client) Close 

func (c *Client) Close() error

Close gracefully closes the websocket connection.

func (*Client) ReadFrame 

func (c *Client) ReadFrame(fr *Frame) (int, error)

ReadFrame ...

func (*Client) Write 

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

func (*Client) WriteFrame 

func (c *Client) WriteFrame(fr *Frame) (int, error)

WriteFrame ...

type CloseHandler 

type CloseHandler func(c *Conn, err error)

type Code 

type Code uint8

Code to send. 

const (
	// CodeContinuation defines the continuation code
	CodeContinuation Code = 0x0
	// CodeText defines the text code
	CodeText Code = 0x1
	// CodeBinary defines the binary code
	CodeBinary Code = 0x2
	// CodeClose defines the close code
	CodeClose Code = 0x8
	// CodePing defines the ping code
	CodePing Code = 0x9
	// CodePong defines the pong code
	CodePong Code = 0xA
)

func (Code) String 

func (code Code) String() string

type Conn added in v0.0.3 

type Conn struct {

	// ReadTimeout ...
	ReadTimeout time.Duration

	// WriteTimeout ...
	WriteTimeout time.Duration

	// MaxPayloadSize prevents huge memory allocation.
	//
	// By default MaxPayloadSize is DefaultPayloadSize.
	MaxPayloadSize uint64
	// contains filtered or unexported fields
}

Conn represents a WebSocket connection on the server side.

This handler is compatible with io.Writer.

func (*Conn) Close added in v0.0.3 

func (c *Conn) Close() error

func (*Conn) ID added in v0.0.3 

func (c *Conn) ID() uint64

ID returns a unique identifier for the connection.

func (*Conn) LocalAddr added in v0.0.3 

func (c *Conn) LocalAddr() net.Addr

LocalAddr returns local address.

func (*Conn) Ping added in v0.0.3 

func (c *Conn) Ping(data []byte)

func (*Conn) RemoteAddr added in v0.0.3 

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns peer remote address.

func (*Conn) SetUserValue added in v0.0.3 

func (c *Conn) SetUserValue(key string, value interface{})

SetUserValue assigns a key to the given value

func (*Conn) UserValue added in v0.0.3 

func (c *Conn) UserValue(key string) interface{}

UserValue returns the key associated value.

func (*Conn) Write added in v0.0.3 

func (c *Conn) Write(data []byte) (int, error)

func (*Conn) WriteFrame added in v0.0.3 

func (c *Conn) WriteFrame(fr *Frame)

type Error 

type Error struct {
	Status StatusCode
	Reason string
}

func (Error) Error 

func (e Error) Error() string

type ErrorHandler 

type ErrorHandler func(c *Conn, err error)

type Frame 

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

Frame is the unit used to transfer message between endpoints using the websocket protocol.

func AcquireFrame 

func AcquireFrame() *Frame

AcquireFrame gets Frame from the global pool.

func (*Frame) Code 

func (fr *Frame) Code() Code

Code returns the code set in fr.

func (*Frame) CopyTo 

func (fr *Frame) CopyTo(fr2 *Frame)

CopyTo copies the frame `fr` to `fr2`

func (*Frame) HasRSV1 

func (fr *Frame) HasRSV1() bool

HasRSV1 checks if RSV1 bit is set.

func (*Frame) HasRSV2 

func (fr *Frame) HasRSV2() bool

HasRSV2 checks if RSV2 bit is set.

func (*Frame) HasRSV3 

func (fr *Frame) HasRSV3() bool

HasRSV3 checks if RSV3 bit is set.

func (*Frame) IsClose 

func (fr *Frame) IsClose() bool

IsClose returns true if Code is CodeClose.

func (*Frame) IsContinuation 

func (fr *Frame) IsContinuation() bool

IsContinuation returns true if the Frame code is Continuation

func (*Frame) IsControl 

func (fr *Frame) IsControl() bool

IsControl returns whether the Frame is a control frame or not. That means if it's a Close, Ping or Pong frame.

func (*Frame) IsFin 

func (fr *Frame) IsFin() bool

IsFin checks if FIN bit is set.

func (*Frame) IsMasked 

func (fr *Frame) IsMasked() bool

IsMasked checks if Mask bit is set.

func (*Frame) IsPing 

func (fr *Frame) IsPing() bool

IsPing returns true if Code is CodePing.

func (*Frame) IsPong 

func (fr *Frame) IsPong() bool

IsPong returns true if Code is CodePong.

func (*Frame) Len 

func (fr *Frame) Len() (length uint64)

Len returns the length of the payload based on the header bits.

If you want to know the actual payload length use #PayloadLen

func (*Frame) Mask 

func (fr *Frame) Mask()

Mask performs the masking of the current payload

func (*Frame) MaskKey 

func (fr *Frame) MaskKey() []byte

MaskKey returns mask key.

Returns zero-padded if doesn't have a mask

func (*Frame) Payload 

func (fr *Frame) Payload() []byte

Payload returns the frame payload.

func (*Frame) PayloadLen 

func (fr *Frame) PayloadLen() int

PayloadLen returns the actual payload length

func (*Frame) PayloadSize 

func (fr *Frame) PayloadSize() uint64

PayloadSize returns the max payload size

func (*Frame) ReadFrom 

func (fr *Frame) ReadFrom(rd io.Reader) (int64, error)

ReadFrom fills fr reading from rd.

func (*Frame) Reset 

func (fr *Frame) Reset()

Reset resets all Frame values to the default.

func (*Frame) SetBinary 

func (fr *Frame) SetBinary()

SetBinary sets CodeText in Code field.

func (*Frame) SetClose 

func (fr *Frame) SetClose()

SetClose sets CodeClose in Code field.

func (*Frame) SetCode 

func (fr *Frame) SetCode(code Code)

SetCode sets code bits.

func (*Frame) SetContinuation 

func (fr *Frame) SetContinuation()

SetContinuation sets CodeContinuation in Code field.

func (*Frame) SetFin 

func (fr *Frame) SetFin()

SetFin sets FIN bit.

func (*Frame) SetMask 

func (fr *Frame) SetMask(b []byte)

SetMask sets the first 4 parsed bytes as mask key and enables the mask bit

func (*Frame) SetPayload 

func (fr *Frame) SetPayload(b []byte)

SetPayload sets the parsed bytes as frame's payload

func (*Frame) SetPayloadSize 

func (fr *Frame) SetPayloadSize(size uint64)

SetPayloadSize sets max payload size

func (*Frame) SetPing 

func (fr *Frame) SetPing()

SetPing sets CodePing in Code field.

func (*Frame) SetPong 

func (fr *Frame) SetPong()

SetPong sets CodePong in Code field.

func (*Frame) SetRSV1 

func (fr *Frame) SetRSV1()

SetRSV1 sets RSV1 bit.

func (*Frame) SetRSV2 

func (fr *Frame) SetRSV2()

SetRSV2 sets RSV2 bit.

func (*Frame) SetRSV3 

func (fr *Frame) SetRSV3()

SetRSV3 sets RSV3 bit.

func (*Frame) SetStatus 

func (fr *Frame) SetStatus(status StatusCode)

SetStatus sets status code.

Status code is usually used in Close request.

func (*Frame) SetText 

func (fr *Frame) SetText()

SetText sets CodeText in Code field.

func (*Frame) Status 

func (fr *Frame) Status() (status StatusCode)

Status returns StatusCode.

func (*Frame) String 

func (fr *Frame) String() string

String returns a representation of Frame in a human-readable string format.

func (*Frame) Unmask 

func (fr *Frame) Unmask()

Unmask performs the unmasking of the current payload

func (*Frame) UnsetMask 

func (fr *Frame) UnsetMask()

UnsetMask only drops the mask bit.

func (*Frame) Write 

func (fr *Frame) Write(b []byte) (int, error)

Write appends the parsed bytes to the frame's payload

func (*Frame) WriteTo 

func (fr *Frame) WriteTo(wr io.Writer) (n int64, err error)

WriteTo writes the frame into wr.

type FrameHandler 

type FrameHandler func(c *Conn, fr *Frame)

type MessageHandler 

type MessageHandler func(c *Conn, isBinary bool, data []byte)

type OpenHandler 

type OpenHandler func(c *Conn)

OpenHandler ...

type PingHandler 

type PingHandler func(c *Conn, data []byte)

type PongHandler 

type PongHandler func(c *Conn, data []byte)

type RequestHandler 

type RequestHandler func(conn *Conn)

RequestHandler is the websocket connection handler.

type Server 

type Server struct {
	// UpgradeHandler allows user to handle RequestCtx when upgrading.
	//
	// If UpgradeHandler returns false the connection won't be upgraded and
	// the parsed ctx will be used as a response.
	UpgradeHandler UpgradeHandler

	// Protocols are the supported protocols.
	Protocols []string

	// Origin is used to limit the clients coming from the defined origin
	Origin string
	// contains filtered or unexported fields
}

Server represents the WebSocket server.

Server is going to be in charge of upgrading the connection, is not a server per-se.

func (*Server) HandleClose 

func (s *Server) HandleClose(closeHandler CloseHandler)

func (*Server) HandleData 

func (s *Server) HandleData(msgHandler MessageHandler)

HandleData sets the MessageHandler.

func (*Server) HandleError 

func (s *Server) HandleError(errHandler ErrorHandler)

func (*Server) HandleFrame 

func (s *Server) HandleFrame(frameHandler FrameHandler)

func (*Server) HandleOpen 

func (s *Server) HandleOpen(openHandler OpenHandler)

func (*Server) HandlePing 

func (s *Server) HandlePing(pingHandler PingHandler)

func (*Server) HandlePong 

func (s *Server) HandlePong(pongHandler PongHandler)

func (*Server) Upgrade 

func (s *Server) Upgrade(ctx *fasthttp.RequestCtx)

type StatusCode 

type StatusCode uint16

StatusCode is sent when closing a connection.

The following constants have been defined by the RFC.

func (StatusCode) String 

func (status StatusCode) String() string

type UpgradeHandler 

type UpgradeHandler func(*fasthttp.RequestCtx) bool

UpgradeHandler is the upgrading handler.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.