websocket

README

English | 中文

extension: websocket

This is an extension combining tnet and gobwas/ws to improve memory usage and performance under millions of connections, while still providing idiomatic usage for websocket protocol.

Features:

• Based upon tnet, reduce memory usage and improve CPU utilization.
• Read/Write for a full message.
• NextMessageReader/NextMessageWriter for user customized read/write.
• Writev for multiple byte slices at server side.
• SetMetadata/GetMetadata to store/retrieve user's private data.
• Customized control frame handler for Ping/Pong/Close.
• Set the message type of the connection to use Read/Write API directly.

Documentation

Overview

Package websocket provides websocket connection interface.

Index

• func LocalAddrFromContext(ctx context.Context) (net.Addr, bool)
• func NewContextWithLocalAddr(ctx context.Context, addr net.Addr) context.Context
• func NewContextWithRemoteAddr(ctx context.Context, addr net.Addr) context.Context
• func NewContextWithWSUpgrader(ctx context.Context, grader *ws.Upgrader) context.Context
• func NewService(ln net.Listener, handler Handler, opts ...ServerOption) (tnet.Service, error)
• func RemoteAddrFromContext(ctx context.Context) (net.Addr, bool)
• func UpgraderFromContext(ctx context.Context) (*ws.Upgrader, bool)
• type ClientOption
  • func WithClientMessageType(tp MessageType) ClientOption
  • func WithClientTLSConfig(cfg *tls.Config) ClientOption
  • func WithSubProtocols(subprotocols []string) ClientOption
  • func WithTimeout(timeout time.Duration) ClientOption
• type Conn
  • func Dial(url string, opts ...ClientOption) (Conn, error)
• type Handler
• type MessageType
  • func (m MessageType) String() string
• type OnClosed
• type ServerOption
  • func WithHookAfterHandshake(hook func(context.Context, Conn) error) ServerOption
  • func WithHookBeforeHandshake(hook func(context.Context) (context.Context, error)) ServerOption
  • func WithIdleTimeout(idleTimeout time.Duration) ServerOption
  • func WithNewHandshakeContext(newContext func() context.Context) ServerOption
  • func WithOnClosed(onClosed func(Conn) error) ServerOption
  • func WithPingHandler(handler func(Conn, []byte) error) ServerOption
  • func WithPongHandler(handler func(Conn, []byte) error) ServerOption
  • func WithProtocolCustom(protocolCustom func([]byte) (string, bool)) ServerOption
  • func WithProtocolSelect(protocolSelect func([]byte) bool) ServerOption
  • func WithServerMessageType(tp MessageType) ServerOption
  • func WithServerTLSConfig(cfg *tls.Config) ServerOption
  • func WithTCPKeepAlive(keepAlive time.Duration) ServerOption

Functions

func LocalAddrFromContext

func LocalAddrFromContext(ctx context.Context) (net.Addr, bool)

LocalAddrFromContext extracts the remote address from context.

func NewContextWithLocalAddr

func NewContextWithLocalAddr(ctx context.Context, addr net.Addr) context.Context

NewContextWithLocalAddr adds the remote address into context.

func NewContextWithRemoteAddr

func NewContextWithRemoteAddr(ctx context.Context, addr net.Addr) context.Context

NewContextWithRemoteAddr adds the remote address into context.

func NewContextWithWSUpgrader

func NewContextWithWSUpgrader(ctx context.Context, grader *ws.Upgrader) context.Context

NewContextWithWSUpgrader creates a context with websocket upgrader.

func NewService

func NewService(ln net.Listener, handler Handler, opts ...ServerOption) (tnet.Service, error)

NewService creates a new websocket service.

func RemoteAddrFromContext

func RemoteAddrFromContext(ctx context.Context) (net.Addr, bool)

RemoteAddrFromContext extracts the remote address from context.

func UpgraderFromContext

func UpgraderFromContext(ctx context.Context) (*ws.Upgrader, bool)

UpgraderFromContext extracts a websocket upgrader from context.

Types

type ClientOption

type ClientOption func(*clientOptions)

ClientOption is the type for a single dial option.

func WithClientMessageType

func WithClientMessageType(tp MessageType) ClientOption

WithClientMessageType provides the option to set message type for each connection created by the client.

func WithClientTLSConfig

func WithClientTLSConfig(cfg *tls.Config) ClientOption

WithClientTLSConfig provides the option to set TLS configuration. To enable TLS, the endpoint must set this option with a non-nil value.

func WithSubProtocols

func WithSubProtocols(subprotocols []string) ClientOption

WithSubProtocols provides the option to set sub protocols.

func WithTimeout

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout provides the option to set dial timeout.

type Conn

type Conn interface {
	net.Conn
	// ReadMessage reads data message.
	ReadMessage() (MessageType, []byte, error)
	// NextMessageReader returns a reader to read the next message.
	NextMessageReader() (MessageType, io.Reader, error)
	// WriteMessage writes message in a single frame.
	WriteMessage(MessageType, []byte) error
	// WritevMessage writes multiple byte slices as a message in a single frame.
	WritevMessage(MessageType, ...[]byte) error
	// NextMessageWriter return a writer to write the next message.
	// A finished message write should end with writer.Close().
	NextMessageWriter(MessageType) (io.WriteCloser, error)
	// SetMetaData sets metadata. Through this method, users can bind some custom data to a connection.
	SetMetaData(any)
	// GetMetaData gets meta data.
	GetMetaData() any
	// Subprotocol returns the negotiated protocol for the connection.
	Subprotocol() string
	// SetPingHandler sets customized Ping frame handler.
	SetPingHandler(handler func(Conn, []byte) error)
	// SetPongHandler sets customized Pong frame handler.
	SetPongHandler(handler func(Conn, []byte) error)
	// SetIdleTimeout sets connection level idle timeout.
	SetIdleTimeout(time.Duration) error
	// SetOnRequest sets request handler for websocket connection.
	// Typically used by websocket client.
	SetOnRequest(handle Handler) error
	// SetOnClosed set on closed function for websocket connection.
	SetOnClosed(handle OnClosed) error
}

Conn provides websocket connection interface.

func Dial

func Dial(url string, opts ...ClientOption) (Conn, error)

Dial creates a client side connection of websocket. url is like: "ws://hostname:port/xxx".

type Handler

type Handler func(c Conn) error

Handler is the websocket connection handler.

type MessageType

type MessageType int

MessageType specifies message types.

const (
	Text MessageType = iota + 1
	Binary
	Ping
	Pong
	Close
)

Message types.

func (MessageType) String

func (m MessageType) String() string

String implements fmt.Stringer.

type OnClosed

type OnClosed func(c Conn) error

OnClosed is the websocket connection on closed function.

type ServerOption

type ServerOption func(*serverOptions)

ServerOption is the type for a single server option.

func WithHookAfterHandshake

func WithHookAfterHandshake(hook func(context.Context, Conn) error) ServerOption

WithHookAfterHandshake provides the option to set after handshake procedures.

func WithHookBeforeHandshake

func WithHookBeforeHandshake(hook func(context.Context) (context.Context, error)) ServerOption

WithHookBeforeHandshake provides the option to set before handshake procedures.

func WithIdleTimeout

func WithIdleTimeout(idleTimeout time.Duration) ServerOption

WithIdleTimeout sets the idle timeout to close the connection.

func WithNewHandshakeContext

func WithNewHandshakeContext(newContext func() context.Context) ServerOption

WithNewHandshakeContext provides the handshake context creator function.

func WithOnClosed

func WithOnClosed(onClosed func(Conn) error) ServerOption

WithOnClosed registers the OnClosed method that is fired when the connection is closed.

func WithPingHandler

func WithPingHandler(handler func(Conn, []byte) error) ServerOption

WithPingHandler provides the option to set customized Ping frame handler for all connections.

func WithPongHandler

func WithPongHandler(handler func(Conn, []byte) error) ServerOption

WithPongHandler provides the option to set customized Pong frame handler for all connections.

func WithProtocolCustom

func WithProtocolCustom(protocolCustom func([]byte) (string, bool)) ServerOption

WithProtocolCustom provides the option for server to parse the "Sec-WebSocket-Protocol" header manually. If protocolCustom is set, it will be used instead of protocolSelect.

func WithProtocolSelect

func WithProtocolSelect(protocolSelect func([]byte) bool) ServerOption

WithProtocolSelect provides the option for server to select a subprotocol from the subprotocol list requested by the client. If this field is set, then the first matched protocol is sent to the client as negotiated.

func WithServerMessageType

func WithServerMessageType(tp MessageType) ServerOption

WithServerMessageType provides the option to set message type for each connection created by the server.

func WithServerTLSConfig

func WithServerTLSConfig(cfg *tls.Config) ServerOption

WithServerTLSConfig provides the option to set TLS configuration. To enable TLS, the endpoint must set this option with a non-nil value.

func WithTCPKeepAlive

func WithTCPKeepAlive(keepAlive time.Duration) ServerOption

WithTCPKeepAlive sets the tcp keep alive interval.