gws

README

gws

Event-Driven Go WebSocket Server & Client

• gws
  • Feature
  • Attention
  • Install
  • Event
  • Quick Start
  • Best Practice
  • Usage
    • KCP
    • Proxy
    • Broadcast
  • Autobahn Test
  • Benchmark
  • Communication
  • Acknowledgments

Feature

• Event API
• Broadcast
• Dial via Proxy
• IO Multiplexing
• Concurrent Write
• Zero Allocs Read/Write (Compression Disabled)
• Passes WebSocket autobahn-testsuite

Attention

• The errors returned by the gws.Conn export methods are ignored, and are handled internally.
• Transferring large files with gws tends to block the connection.
• If HTTP Server is reused, it is recommended to enable goroutine, as blocking will prevent the context from being GC.

Install

go get -v github.com/lxzan/gws@latest

Event

type Event interface {
	OnOpen(socket *Conn)
	OnClose(socket *Conn, err error)
	OnPing(socket *Conn, payload []byte)
	OnPong(socket *Conn, payload []byte)
	OnMessage(socket *Conn, message *Message)
}

Quick Start

package main

import "github.com/lxzan/gws"

func main() {
	gws.NewServer(new(gws.BuiltinEventHandler), nil).Run(":6666")
}

Best Practice

package main

import (
	"github.com/lxzan/gws"
	"net/http"
	"time"
)

const (
	PingInterval = 10 * time.Second
	PingWait     = 5 * time.Second
)

func main() {
	upgrader := gws.NewUpgrader(&Handler{}, &gws.ServerOption{
		ReadAsyncEnabled: true,
		CompressEnabled:  true,
	})
	http.HandleFunc("/connect", func(writer http.ResponseWriter, request *http.Request) {
		socket, err := upgrader.Upgrade(writer, request)
		if err != nil {
			return
		}
		go func() {
			// Blocking prevents the context from being GC.
			socket.ReadLoop()
		}()
	})
	http.ListenAndServe(":6666", nil)
}

type Handler struct{}

func (c *Handler) OnOpen(socket *gws.Conn) {
	_ = socket.SetDeadline(time.Now().Add(PingInterval + PingWait))
}

func (c *Handler) OnClose(socket *gws.Conn, err error) {}

func (c *Handler) OnPing(socket *gws.Conn, payload []byte) {
	_ = socket.SetDeadline(time.Now().Add(PingInterval + PingWait))
	_ = socket.WritePong(nil)
}

func (c *Handler) OnPong(socket *gws.Conn, payload []byte) {}

func (c *Handler) OnMessage(socket *gws.Conn, message *gws.Message) {
	defer message.Close()
	socket.WriteMessage(message.Opcode, message.Bytes())
}

Usage

KCP

• server

package main

import (
	"log"
	"github.com/lxzan/gws"
	kcp "github.com/xtaci/kcp-go"
)

func main() {
	listener, err := kcp.Listen(":6666")
	if err != nil {
		log.Println(err.Error())
		return
	}
	app := gws.NewServer(&gws.BuiltinEventHandler{}, nil)
	app.RunListener(listener)
}

• client

package main

import (
	"github.com/lxzan/gws"
	kcp "github.com/xtaci/kcp-go"
	"log"
)

func main() {
	conn, err := kcp.Dial("127.0.0.1:6666")
	if err != nil {
		log.Println(err.Error())
		return
	}
	app, _, err := gws.NewClientFromConn(&gws.BuiltinEventHandler{}, nil, conn)
	if err != nil {
		log.Println(err.Error())
		return
	}
	app.ReadLoop()
}

Proxy

package main

import (
	"crypto/tls"
	"github.com/lxzan/gws"
	"golang.org/x/net/proxy"
	"log"
)

func main() {
	socket, _, err := gws.NewClient(new(gws.BuiltinEventHandler), &gws.ClientOption{
		Addr:      "wss://example.com/connect",
		TlsConfig: &tls.Config{InsecureSkipVerify: true},
		NewDialer: func() (gws.Dialer, error) {
			return proxy.SOCKS5("tcp", "127.0.0.1:1080", nil, nil)
		},
	})
	if err != nil {
		log.Println(err.Error())
		return
	}
	socket.ReadLoop()
}

Broadcast

func Broadcast(conns []*gws.Conn, opcode gws.Opcode, payload []byte) {
	var b = gws.NewBroadcaster(opcode, payload)
	defer b.Release()
	for _, item := range conns {
		_ = b.Broadcast(item)
	}
}

Autobahn Test

cd examples/autobahn
mkdir reports
docker run -it --rm \
    -v ${PWD}/config:/config \
    -v ${PWD}/reports:/reports \
    crossbario/autobahn-testsuite \
    wstest -m fuzzingclient -s /config/fuzzingclient.json

Benchmark

• GOMAXPROCS = 4
• Connection = 1000
• Compress Disabled

$ go test -benchmem -run=^$ -bench ^(BenchmarkConn_WriteMessage|BenchmarkConn_ReadMessage)$ github.com/lxzan/gws

goos: darwin
goarch: arm64
pkg: github.com/lxzan/gws
BenchmarkConn_WriteMessage/compress_disabled-8           8713082               138.0 ns/op             0 B/op          0 allocs/op
BenchmarkConn_WriteMessage/compress_enabled-8             144266              8066 ns/op             235 B/op          0 allocs/op
BenchmarkConn_ReadMessage/compress_disabled-8           11608689               102.8 ns/op            12 B/op          0 allocs/op
BenchmarkConn_ReadMessage/compress_enabled-8              435176              2498 ns/op              98 B/op          1 allocs/op

Communication

微信二维码在讨论区不定时更新

    

Acknowledgments

The following project had particular influence on gws's design.

• crossbario/autobahn-testsuite
• klauspost/compress
• lesismal/nbio

Documentation

Index

• Variables
• type Broadcaster
  • func NewBroadcaster(opcode Opcode, payload []byte) *Broadcaster
  • func (c *Broadcaster) Broadcast(socket *Conn) error
  • func (c *Broadcaster) Release()
• type BuiltinEventHandler
  • func (b BuiltinEventHandler) OnClose(socket *Conn, err error)
  • func (b BuiltinEventHandler) OnMessage(socket *Conn, message *Message)
  • func (b BuiltinEventHandler) OnOpen(socket *Conn)
  • func (b BuiltinEventHandler) OnPing(socket *Conn, payload []byte)
  • func (b BuiltinEventHandler) OnPong(socket *Conn, payload []byte)
• type ClientOption
• type CloseError
  • func (c *CloseError) Error() string
• type Comparable
• type ConcurrentMap
  • func NewConcurrentMap[K Comparable, V any](segments uint64) *ConcurrentMap[K, V]
  • func (c *ConcurrentMap[K, V]) Delete(key K)
  • func (c *ConcurrentMap[K, V]) Len() int
  • func (c *ConcurrentMap[K, V]) Load(key K) (value V, exist bool)
  • func (c *ConcurrentMap[K, V]) Range(f func(key K, value V) bool)
  • func (c *ConcurrentMap[K, V]) Store(key K, value V)
• type Config
• type Conn
  • func NewClient(handler Event, option *ClientOption) (*Conn, *http.Response, error)
  • func NewClientFromConn(handler Event, option *ClientOption, conn net.Conn) (*Conn, *http.Response, error)
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) NetConn() net.Conn
  • func (c *Conn) ReadLoop()
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetNoDelay(noDelay bool) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) SubProtocol() string
  • func (c *Conn) WriteAsync(opcode Opcode, payload []byte) error
  • func (c *Conn) WriteClose(code uint16, reason []byte)
  • func (c *Conn) WriteMessage(opcode Opcode, payload []byte) error
  • func (c *Conn) WritePing(payload []byte) error
  • func (c *Conn) WritePong(payload []byte) error
  • func (c *Conn) WriteString(s string) error
• type Dialer
• type Event
• type Message
  • func (c *Message) Bytes() []byte
  • func (c *Message) Close() error
  • func (c *Message) Read(p []byte) (n int, err error)
• type Opcode
• type Server
  • func NewServer(eventHandler Event, option *ServerOption) *Server
  • func (c *Server) Run(addr string) error
  • func (c *Server) RunListener(listener net.Listener) error
  • func (c *Server) RunTLS(addr string, certFile, keyFile string) error
• type ServerOption
• type SessionStorage
• type Upgrader
  • func NewUpgrader(eventHandler Event, option *ServerOption) *Upgrader
  • func (c *Upgrader) Upgrade(w http.ResponseWriter, r *http.Request) (*Conn, error)

Variables

var (

	// ErrUnauthorized 未通过鉴权认证
	// Failure to pass forensic authentication
	ErrUnauthorized = errors.New("unauthorized")

	// ErrHandshake 握手错误, 请求头未通过校验
	// Handshake error, request header does not pass checksum.
	ErrHandshake = errors.New("handshake error")

	// ErrCompressionNegotiation 压缩拓展协商失败, 请尝试关闭压缩
	// Compression extension negotiation failed, please try to disable compression.
	ErrCompressionNegotiation = errors.New("invalid compression negotiation")

	// ErrSubprotocolNegotiation 子协议协商失败
	// Sub-protocol negotiation failed
	ErrSubprotocolNegotiation = errors.New("sub-protocol negotiation failed")

	// ErrTextEncoding 文本消息编码错误(必须是utf8编码)
	// Text message encoding error (must be utf8)
	ErrTextEncoding = errors.New("invalid text encoding")

	// ErrConnClosed 连接已关闭
	// Connection closed
	ErrConnClosed = net.ErrClosed

	// ErrUnsupportedProtocol 不支持的网络协议
	// Unsupported network protocols
	ErrUnsupportedProtocol = errors.New("unsupported protocol")
)

Types

type Broadcaster

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

func NewBroadcaster

func NewBroadcaster(opcode Opcode, payload []byte) *Broadcaster

NewBroadcaster 创建广播器 相比循环调用WriteAsync, Broadcaster只会压缩一次消息, 可以节省大量CPU开销. Instead of calling WriteAsync in a loop, Broadcaster compresses the message only once, saving a lot of CPU overhead.

func (*Broadcaster) Broadcast

func (c *Broadcaster) Broadcast(socket *Conn) error

Broadcast 广播 向客户端发送广播消息 Send a broadcast message to a client.

func (*Broadcaster) Release

func (c *Broadcaster) Release()

Release 释放资源 在完成所有Broadcast调用之后执行Release方法释放资源. Call the Release method after all the Broadcasts have been completed to release the resources.

type BuiltinEventHandler

type BuiltinEventHandler struct{}

func (BuiltinEventHandler) OnClose

func (b BuiltinEventHandler) OnClose(socket *Conn, err error)

func (BuiltinEventHandler) OnMessage

func (b BuiltinEventHandler) OnMessage(socket *Conn, message *Message)

func (BuiltinEventHandler) OnOpen

func (b BuiltinEventHandler) OnOpen(socket *Conn)

func (BuiltinEventHandler) OnPing

func (b BuiltinEventHandler) OnPing(socket *Conn, payload []byte)

func (BuiltinEventHandler) OnPong

func (b BuiltinEventHandler) OnPong(socket *Conn, payload []byte)

type ClientOption

type ClientOption struct {
	// 写缓冲区的大小, v1.4.5版本此参数被废弃
	// Deprecated: Size of the write buffer, v1.4.5 version of this parameter is deprecated
	WriteBufferSize int

	ReadAsyncEnabled    bool
	ReadAsyncGoLimit    int
	ReadMaxPayloadSize  int
	ReadBufferSize      int
	WriteMaxPayloadSize int
	CompressEnabled     bool
	CompressLevel       int
	CompressThreshold   int
	CheckUtf8Enabled    bool

	// 连接地址, 例如 wss://example.com/connect
	// server address, eg: wss://example.com/connect
	Addr string

	// 额外的请求头
	// extra request header
	RequestHeader http.Header

	// 握手超时时间
	HandshakeTimeout time.Duration

	// TLS设置
	TlsConfig *tls.Config

	// 拨号器
	// 默认是返回net.Dialer实例, 也可以用于设置代理.
	// The default is to return the net.Dialer instance
	// Can also be used to set a proxy, for example
	// NewDialer: func() (proxy.Dialer, error) {
	//		return proxy.SOCKS5("tcp", "127.0.0.1:1080", nil, nil)
	// },
	NewDialer func() (Dialer, error)

	// 创建session存储空间
	// 用于自定义SessionStorage实现
	// For custom SessionStorage implementations
	NewSessionStorage func() SessionStorage
}

type CloseError

type CloseError struct {
	Code   uint16
	Reason []byte
}

func (*CloseError) Error

func (c *CloseError) Error() string

type Comparable

type Comparable interface {
	~string | ~int | ~int64 | ~int32 | ~uint | ~uint64 | ~uint32
}

type ConcurrentMap

type ConcurrentMap[K Comparable, V any] struct {
	// contains filtered or unexported fields
}

func NewConcurrentMap

func NewConcurrentMap[K Comparable, V any](segments uint64) *ConcurrentMap[K, V]

func (*ConcurrentMap[K, V]) Delete

func (c *ConcurrentMap[K, V]) Delete(key K)

func (*ConcurrentMap[K, V]) Len

func (c *ConcurrentMap[K, V]) Len() int

func (*ConcurrentMap[K, V]) Load

func (c *ConcurrentMap[K, V]) Load(key K) (value V, exist bool)

func (*ConcurrentMap[K, V]) Range

func (c *ConcurrentMap[K, V]) Range(f func(key K, value V) bool)

Range calls f sequentially for each key and value present in the map. If f returns false, range stops the iteration.

func (*ConcurrentMap[K, V]) Store

func (c *ConcurrentMap[K, V]) Store(key K, value V)

type Config

type Config struct {

	// 是否开启异步读, 开启的话会并行调用OnMessage
	// Whether to enable asynchronous reading, if enabled OnMessage will be called in parallel
	ReadAsyncEnabled bool

	// 异步读的最大并行协程数量
	// Maximum number of parallel concurrent processes for asynchronous reads
	ReadAsyncGoLimit int

	// 最大读取的消息内容长度
	// Maximum read message content length
	ReadMaxPayloadSize int

	// 读缓冲区的大小
	// Size of the read buffer
	ReadBufferSize int

	// 最大写入的消息内容长度
	// Maximum length of written message content
	WriteMaxPayloadSize int

	// 写缓冲区的大小, v1.4.5版本此参数被废弃
	// Deprecated: Size of the write buffer, v1.4.5 version of this parameter is deprecated
	WriteBufferSize int

	// 是否开启数据压缩
	// Whether to turn on data compression
	CompressEnabled bool

	// 压缩级别
	// Compress level
	CompressLevel int

	// 压缩阈值, 低于阈值的消息不会被压缩
	// Compression threshold, messages below the threshold will not be compressed
	CompressThreshold int

	// CompressorNum 压缩器数量
	// 数值越大竞争的概率越小, 但是会耗费大量内存, 注意取舍
	// Number of compressors
	// The higher the value the lower the probability of competition, but it will consume a lot of memory, so be careful about the trade-off
	CompressorNum int

	// 是否检查文本utf8编码, 关闭性能会好点
	// Whether to check the text utf8 encoding, turn off the performance will be better
	CheckUtf8Enabled bool
	// contains filtered or unexported fields
}

type Conn

type Conn struct {
	SessionStorage SessionStorage // 会话
	// contains filtered or unexported fields
}

func NewClient

func NewClient(handler Event, option *ClientOption) (*Conn, *http.Response, error)

NewClient 创建客户端 Create New client

func NewClientFromConn

func NewClientFromConn(handler Event, option *ClientOption, conn net.Conn) (*Conn, *http.Response, error)

NewClientFromConn 通过外部连接创建客户端, 支持 TCP/KCP/Unix Domain Socket Create New client via external connection, supports TCP/KCP/Unix Domain Socket.

func (*Conn) LocalAddr

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

func (*Conn) NetConn

func (c *Conn) NetConn() net.Conn

NetConn get tcp/tls/kcp... connection

func (*Conn) ReadLoop

func (c *Conn) ReadLoop()

ReadLoop 循环读取消息. 如果复用了HTTP Server, 建议开启goroutine, 阻塞会导致请求上下文无法被GC. Read messages in a loop. If HTTP Server is reused, it is recommended to enable goroutine, as blocking will prevent the context from being GC.

func (*Conn) RemoteAddr

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

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets deadline

func (*Conn) SetNoDelay

func (c *Conn) SetNoDelay(noDelay bool) error

SetNoDelay controls whether the operating system should delay packet transmission in hopes of sending fewer packets (Nagle's algorithm). The default is true (no delay), meaning that data is sent as soon as possible after a Write.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets read deadline

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets write deadline

func (*Conn) SubProtocol

func (c *Conn) SubProtocol() string

SubProtocol 获取协商的子协议 Get negotiated sub-protocols

func (*Conn) WriteAsync

func (c *Conn) WriteAsync(opcode Opcode, payload []byte) error

WriteAsync 异步非阻塞地写入消息 Write messages asynchronously and non-blocking

func (*Conn) WriteClose

func (c *Conn) WriteClose(code uint16, reason []byte)

WriteClose 发送关闭帧, 主动断开连接 没有特殊需求的话, 推荐code=1000, reason=nil Send shutdown frame, active disconnection If you don't have any special needs, we recommend code=1000, reason=nil https://developer.mozilla.org/zh-CN/docs/Web/API/CloseEvent#status_codes

func (*Conn) WriteMessage

func (c *Conn) WriteMessage(opcode Opcode, payload []byte) error

WriteMessage 写入文本/二进制消息, 文本消息应该使用UTF8编码 Write text/binary messages, text messages should be encoded in UTF8.

func (*Conn) WritePing

func (c *Conn) WritePing(payload []byte) error

WritePing 写入Ping消息, 携带的信息不要超过125字节 Control frame length cannot exceed 125 bytes

func (*Conn) WritePong

func (c *Conn) WritePong(payload []byte) error

WritePong 写入Pong消息, 携带的信息不要超过125字节 Control frame length cannot exceed 125 bytes

func (*Conn) WriteString

func (c *Conn) WriteString(s string) error

WriteString 写入文本消息, 使用UTF8编码. Write text messages, should be encoded in UTF8.

type Dialer

type Dialer interface {
	Dial(network, addr string) (c net.Conn, err error)
}

type Event

type Event interface {
	// OnOpen 建立连接事件
	// WebSocket connection was successfully established
	OnOpen(socket *Conn)

	// OnClose 关闭事件
	// 接收到了网络连接另一端发送的关闭帧, 或者IO过程中出现错误主动断开连接
	// 如果是前者, err可以断言为*CloseError
	// Received a close frame from the other end of the network connection, or disconnected voluntarily due to an error in the IO process
	// In the former case, err can be asserted as *CloseError
	OnClose(socket *Conn, err error)

	// OnPing 心跳探测事件
	// Received a ping frame
	OnPing(socket *Conn, payload []byte)

	// OnPong 心跳响应事件
	// Received a pong frame
	OnPong(socket *Conn, payload []byte)

	// OnMessage 消息事件
	// 如果开启了ReadAsyncEnabled, 会并行地调用OnMessage; 没有做recover处理.
	// If ReadAsyncEnabled is enabled, OnMessage is called in parallel. No recover is done.
	OnMessage(socket *Conn, message *Message)
}

type Message

type Message struct {

	// 操作码
	Opcode Opcode

	// 消息内容
	Data *bytes.Buffer
	// contains filtered or unexported fields
}

func (*Message) Bytes

func (c *Message) Bytes() []byte

func (*Message) Close

func (c *Message) Close() error

Close recycle buffer

func (*Message) Read

func (c *Message) Read(p []byte) (n int, err error)

type Opcode

type Opcode uint8

const (
	OpcodeContinuation    Opcode = 0x0
	OpcodeText            Opcode = 0x1
	OpcodeBinary          Opcode = 0x2
	OpcodeCloseConnection Opcode = 0x8
	OpcodePing            Opcode = 0x9
	OpcodePong            Opcode = 0xA
)

type Server

type Server struct {

	// OnError 接收握手过程中产生的错误回调
	// Receive error callbacks generated during the handshake
	OnError func(conn net.Conn, err error)

	// OnRequest
	OnRequest func(socket *Conn, request *http.Request)
	// contains filtered or unexported fields
}

func NewServer

func NewServer(eventHandler Event, option *ServerOption) *Server

NewServer 创建websocket服务器 create a websocket server

func (*Server) Run

func (c *Server) Run(addr string) error

Run runs ws server addr: Address of the listener

func (*Server) RunListener

func (c *Server) RunListener(listener net.Listener) error

func (*Server) RunTLS

func (c *Server) RunTLS(addr string, certFile, keyFile string) error

RunTLS runs wss server addr: Address of the listener config: tls config

type ServerOption

type ServerOption struct {

	// 写缓冲区的大小, v1.4.5版本此参数被废弃
	// Deprecated: Size of the write buffer, v1.4.5 version of this parameter is deprecated
	WriteBufferSize int

	ReadAsyncEnabled    bool
	ReadAsyncGoLimit    int
	ReadMaxPayloadSize  int
	ReadBufferSize      int
	WriteMaxPayloadSize int
	CompressEnabled     bool
	CompressLevel       int
	CompressThreshold   int
	CompressorNum       int
	CheckUtf8Enabled    bool

	// 握手超时时间
	HandshakeTimeout time.Duration

	// WebSocket子协议, 握手失败会断开连接
	// WebSocket sub-protocol, handshake failure disconnects the connection
	SubProtocols []string

	// 额外的响应头(可能不受客户端支持)
	// Additional response headers (may not be supported by the client)
	// https://www.rfc-editor.org/rfc/rfc6455.html#section-1.3
	ResponseHeader http.Header

	// 鉴权
	// Authentication of requests for connection establishment
	Authorize func(r *http.Request, session SessionStorage) bool

	// 创建session存储空间
	// 用于自定义SessionStorage实现
	// For custom SessionStorage implementations
	NewSessionStorage func() SessionStorage
	// contains filtered or unexported fields
}

type SessionStorage

type SessionStorage interface {
	Load(key string) (value interface{}, exist bool)
	Delete(key string)
	Store(key string, value interface{})
	Range(f func(key string, value interface{}) bool)
}

type Upgrader

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

func NewUpgrader

func NewUpgrader(eventHandler Event, option *ServerOption) *Upgrader

func (*Upgrader) Upgrade

func (c *Upgrader) Upgrade(w http.ResponseWriter, r *http.Request) (*Conn, error)

Upgrade http upgrade to websocket protocol