websocket

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2018 License: MIT Imports: 15 Imported by: 6

README

Build Status License Releases Read me docs Build Status Built with GoLang Platforms

The package go-websocket provides an easy way to setup a rich Websocket server and client side.

It's already tested on production & used on Iris.

Installation

The only requirement is the Go Programming Language.

$ go get -u github.com/kataras/go-websocket

Examples

To view working examples please navigate to the ./examples folder.

Docs

WebSocket is a protocol providing full-duplex communication channels over a single TCP connection. The WebSocket protocol was standardized by the IETF as RFC 6455 in 2011, and the WebSocket API in Web IDL is being standardized by the W3C.

WebSocket is designed to be implemented in web browsers and web servers, but it can be used by any client or server application. The WebSocket protocol is an independent TCP-based protocol. Its only relationship to HTTP is that its handshake is interpreted by HTTP servers as an Upgrade request. The WebSocket protocol makes more interaction between a browser and a website possible, facilitating real-time data transfer from and to the server.

Read more about Websockets on Wikipedia.

Configuration

// Config the websocket server configuration
type Config struct {
    // IDGenerator used to create (and later on, set)
    // an ID for each incoming websocket connections (clients).
    // The request is an input parameter which you can use to generate the ID (from headers for example).
    // If empty then the ID is generated by DefaultIDGenerator: uuid or,if failed, a randomString(64)
    IDGenerator func(w http.ResponseWriter, r *http.Request) string
    // EvtMessagePrefix is the prefix of the underline websocket events that are being established under the hoods.
    // This prefix is visible only to the javascript side (code) and it has nothing to do
    // with the message that the end-user receives.
    // Do not change it unless it is absolutely necessary.
    //
    // If empty then defaults to []byte("go-websocket-message:").
    EvtMessagePrefix []byte
    // Error is the function that will be fired if any client couldn't upgrade the HTTP connection
    // to a websocket connection, a handshake error.
    Error func(w http.ResponseWriter, r *http.Request, status int, reason error)
    // CheckOrigin a function that is called right before the handshake,
    // if returns false then that client is not allowed to connect with the websocket server.
    CheckOrigin func(r *http.Request) bool
    // HandshakeTimeout specifies the duration for the handshake to complete.
    HandshakeTimeout time.Duration
    // WriteTimeout time allowed to write a message to the connection.
    // 0 means no timeout.
    // Default value is 0
    WriteTimeout time.Duration
    // ReadTimeout time allowed to read a message from the connection.
    // 0 means no timeout.
    // Default value is 0
    ReadTimeout time.Duration
    // PongTimeout allowed to read the next pong message from the connection.
    // Default value is 60 * time.Second
    PongTimeout time.Duration
    // PingPeriod send ping messages to the connection within this period. Must be less than PongTimeout.
    // Default value is 60 *time.Second
    PingPeriod time.Duration
    // MaxMessageSize max message size allowed from connection.
    // Default value is 1024
    MaxMessageSize int64
    // BinaryMessages set it to true in order to denotes binary data messages instead of utf-8 text
    // compatible if you wanna use the Connection's EmitMessage to send a custom binary data to the client, like a native server-client communication.
    // Default value is false
    BinaryMessages bool
    // ReadBufferSize is the buffer size for the connection reader.
    // Default value is 4096
    ReadBufferSize int
    // WriteBufferSize is the buffer size for the connection writer.
    // Default value is 4096
    WriteBufferSize int
    // EnableCompression specify if the server should attempt to negotiate per
    // message compression (RFC 7692). Setting this value to true does not
    // guarantee that compression will be supported. Currently only "no context
    // takeover" modes are supported.
    //
    // Defaults to false and it should be remain as it is, unless special requirements.
    EnableCompression bool

    // Subprotocols specifies the server's supported protocols in order of
    // preference. If this field is set, then the Upgrade method negotiates a
    // subprotocol by selecting the first match in this list with a protocol
    // requested by the client.
    Subprotocols []string
}

OUTLINE

// ws := websocket.New(websocket.Config...{})
// ws.websocket.OnConnection(func(c websocket.Connection){})
// or package-default
websocket.OnConnection(func(c websocket.Connection){})

Connection's methods

ID() string

Request() *http.Request

// Receive from the client
On("anyCustomEvent", func(message string) {})
On("anyCustomEvent", func(message int){})
On("anyCustomEvent", func(message bool){})
On("anyCustomEvent", func(message anyCustomType){})
On("anyCustomEvent", func(){})

// Receive a native websocket message from the client
// compatible without need of import the go-websocket.js to the .html
OnMessage(func(message []byte){})

// Send to the client
Emit("anyCustomEvent", string)
Emit("anyCustomEvent", int)
Emit("anyCustomEvent", bool)
Emit("anyCustomEvent", anyCustomType)

// Send native websocket messages
// with config.BinaryMessages = true
// useful when you use proto or something like this.
//
// compatible without need of import the go-websocket.js to the .html
EmitMessage([]byte("anyMessage"))

// Send to specific client(s)
To("otherConnectionId").Emit/EmitMessage...
To("anyCustomRoom").Emit/EmitMessage...

// Send to all opened connections/clients
To(websocket.All).Emit/EmitMessage...

// Send to all opened connections/clients EXCEPT this client
To(websocket.Broadcast).Emit/EmitMessage...

// Rooms, group of connections/clients
Join("anyCustomRoom")
Leave("anyCustomRoom")


// Fired when the connection is closed
OnDisconnect(func(){})

// Force-disconnect the client from the server-side
Disconnect() error

FAQ

Explore these questions or navigate to the community chat.

Versioning

Current: v0.1.0

People

The author of go-websocket is @kataras.

If you're willing to donate, feel free to send any amount through paypal

Contributing

If you are interested in contributing to the go-websocket project, please make a PR.

License

This project is licensed under the MIT License.

License can be found here.

Documentation

Overview

Package websocket provides an easy way to setup a rich Websocket server and client side. See _examples/chat for more.

Index

Constants

View Source 
const (
	// DefaultWebsocketWriteTimeout 0, no timeout
	DefaultWebsocketWriteTimeout = 0
	// DefaultWebsocketReadTimeout 0, no timeout
	DefaultWebsocketReadTimeout = 0
	// DefaultWebsocketPongTimeout 60 * time.Second
	DefaultWebsocketPongTimeout = 60 * time.Second
	// DefaultWebsocketPingPeriod (DefaultPongTimeout * 9) / 10
	DefaultWebsocketPingPeriod = (DefaultWebsocketPongTimeout * 9) / 10
	// DefaultWebsocketMaxMessageSize 1024
	DefaultWebsocketMaxMessageSize = 1024
	// DefaultWebsocketReadBufferSize 4096
	DefaultWebsocketReadBufferSize = 4096
	// DefaultWebsocketWriterBufferSize 4096
	DefaultWebsocketWriterBufferSize = 4096
	// DefaultEvtMessageKey is the default prefix of the underline websocket events
	// that are being established under the hoods.
	//
	// Defaults to "go-websocket-message:".
	// Last character of the prefix should be ':'.
	DefaultEvtMessageKey = "go-websocket-message:"
)
View Source 
const (
	// All is the string which the Emitter use to send a message to all.
	All = ""
	// Broadcast is the string which the Emitter use to send a message to all except this connection.
	Broadcast = ";to;all;except;me;"
)
View Source 
const CloseMessage = websocket.CloseMessage

CloseMessage denotes a close control message. The optional message payload contains a numeric code and text. Use the FormatCloseMessage function to format a close message payload.

Use the `Connection#Disconnect` instead.

View Source 
const (
	// Version is the current go-websocket semantic version.
	Version = "0.2.0"
)
View Source 
const (
	// WriteWait is 1 second at the internal implementation,
	// same as here but this can be changed at the future*
	WriteWait = 1 * time.Second
)

Variables

View Source 
var ClientSource = []byte(`var websocketStringMessageType = 0;
var websocketIntMessageType = 1; 
var websocketBoolMessageType = 2;
var websocketJSONMessageType = 4;
var websocketMessagePrefix = "` + DefaultEvtMessageKey + `";
var websocketMessageSeparator = ";";
var websocketMessagePrefixLen = websocketMessagePrefix.length;
var websocketMessageSeparatorLen = websocketMessageSeparator.length;
var websocketMessagePrefixAndSepIdx = websocketMessagePrefixLen + websocketMessageSeparatorLen - 1;
var websocketMessagePrefixIdx = websocketMessagePrefixLen - 1;
var websocketMessageSeparatorIdx = websocketMessageSeparatorLen - 1;
var Ws = (function () {
    //
    function Ws(endpoint, protocols) {
        var _this = this;
        // events listeners
        this.connectListeners = [];
        this.disconnectListeners = [];
        this.nativeMessageListeners = [];
        this.messageListeners = {};
        if (!window["WebSocket"]) {
            return;
        }
        if (endpoint.indexOf("ws") == -1) {
            endpoint = "ws://" + endpoint;
        }
        if (protocols != null && protocols.length > 0) {
            this.conn = new WebSocket(endpoint, protocols);
        }
        else {
            this.conn = new WebSocket(endpoint);
        }
        this.conn.onopen = (function (evt) {
            _this.fireConnect();
            _this.isReady = true;
            return null;
        });
        this.conn.onclose = (function (evt) {
            _this.fireDisconnect();
            return null;
        });
        this.conn.onmessage = (function (evt) {
            _this.messageReceivedFromConn(evt);
        });
    }
    //utils
    Ws.prototype.isNumber = function (obj) {
        return !isNaN(obj - 0) && obj !== null && obj !== "" && obj !== false;
    };
    Ws.prototype.isString = function (obj) {
        return Object.prototype.toString.call(obj) == "[object String]";
    };
    Ws.prototype.isBoolean = function (obj) {
        return typeof obj === 'boolean' ||
            (typeof obj === 'object' && typeof obj.valueOf() === 'boolean');
    };
    Ws.prototype.isJSON = function (obj) {
        return typeof obj === 'object';
    };
    //
    // messages
    Ws.prototype._msg = function (event, websocketMessageType, dataMessage) {
        return websocketMessagePrefix + event + websocketMessageSeparator + String(websocketMessageType) + websocketMessageSeparator + dataMessage;
    };
    Ws.prototype.encodeMessage = function (event, data) {
        var m = "";
        var t = 0;
        if (this.isNumber(data)) {
            t = websocketIntMessageType;
            m = data.toString();
        }
        else if (this.isBoolean(data)) {
            t = websocketBoolMessageType;
            m = data.toString();
        }
        else if (this.isString(data)) {
            t = websocketStringMessageType;
            m = data.toString();
        }
        else if (this.isJSON(data)) {
            //propably json-object
            t = websocketJSONMessageType;
            m = JSON.stringify(data);
        }
        else if (data !== null && typeof(data) !== "undefined" ) {
            // if it has a second parameter but it's not a type we know, then fire this:
            console.log("unsupported type of input argument passed, try to not include this argument to the 'Emit'");
        }
        return this._msg(event, t, m);
    };
    Ws.prototype.decodeMessage = function (event, websocketMessage) {
        //go-websocket-message;user;4;themarshaledstringfromajsonstruct
        var skipLen = websocketMessagePrefixLen + websocketMessageSeparatorLen + event.length + 2;
        if (websocketMessage.length < skipLen + 1) {
            return null;
        }
        var websocketMessageType = parseInt(websocketMessage.charAt(skipLen - 2));
        var theMessage = websocketMessage.substring(skipLen, websocketMessage.length);
        if (websocketMessageType == websocketIntMessageType) {
            return parseInt(theMessage);
        }
        else if (websocketMessageType == websocketBoolMessageType) {
            return Boolean(theMessage);
        }
        else if (websocketMessageType == websocketStringMessageType) {
            return theMessage;
        }
        else if (websocketMessageType == websocketJSONMessageType) {
            return JSON.parse(theMessage);
        }
        else {
            return null; // invalid
        }
    };
    Ws.prototype.getWebsocketCustomEvent = function (websocketMessage) {
        if (websocketMessage.length < websocketMessagePrefixAndSepIdx) {
            return "";
        }
        var s = websocketMessage.substring(websocketMessagePrefixAndSepIdx, websocketMessage.length);
        var evt = s.substring(0, s.indexOf(websocketMessageSeparator));
        return evt;
    };
    Ws.prototype.getCustomMessage = function (event, websocketMessage) {
        var eventIdx = websocketMessage.indexOf(event + websocketMessageSeparator);
        var s = websocketMessage.substring(eventIdx + event.length + websocketMessageSeparator.length + 2, websocketMessage.length);
        return s;
    };
    //
    // Ws Events
    // messageReceivedFromConn this is the func which decides
    // if it's a native websocket message or a custom qws message
    // if native message then calls the fireNativeMessage
    // else calls the fireMessage
    //
    // remember this library gives you the freedom of native websocket messages if you don't want to use this client side at all.
    Ws.prototype.messageReceivedFromConn = function (evt) {
        //check if qws message
        var message = evt.data;
        if (message.indexOf(websocketMessagePrefix) != -1) {
            var event_1 = this.getWebsocketCustomEvent(message);
            if (event_1 != "") {
                // it's a custom message
                this.fireMessage(event_1, this.getCustomMessage(event_1, message));
                return;
            }
        }
        // it's a native websocket message
        this.fireNativeMessage(message);
    };
    Ws.prototype.OnConnect = function (fn) {
        if (this.isReady) {
            fn();
        }
        this.connectListeners.push(fn);
    };
    Ws.prototype.fireConnect = function () {
        for (var i = 0; i < this.connectListeners.length; i++) {
            this.connectListeners[i]();
        }
    };
    Ws.prototype.OnDisconnect = function (fn) {
        this.disconnectListeners.push(fn);
    };
    Ws.prototype.fireDisconnect = function () {
        for (var i = 0; i < this.disconnectListeners.length; i++) {
            this.disconnectListeners[i]();
        }
    };
    Ws.prototype.OnMessage = function (cb) {
        this.nativeMessageListeners.push(cb);
    };
    Ws.prototype.fireNativeMessage = function (websocketMessage) {
        for (var i = 0; i < this.nativeMessageListeners.length; i++) {
            this.nativeMessageListeners[i](websocketMessage);
        }
    };
    Ws.prototype.On = function (event, cb) {
        if (this.messageListeners[event] == null || this.messageListeners[event] == undefined) {
            this.messageListeners[event] = [];
        }
        this.messageListeners[event].push(cb);
    };
    Ws.prototype.fireMessage = function (event, message) {
        for (var key in this.messageListeners) {
            if (this.messageListeners.hasOwnProperty(key)) {
                if (key == event) {
                    for (var i = 0; i < this.messageListeners[key].length; i++) {
                        this.messageListeners[key][i](message);
                    }
                }
            }
        }
    };
    //
    // Ws Actions
    Ws.prototype.Disconnect = function () {
        this.conn.close();
    };
    // EmitMessage sends a native websocket message
    Ws.prototype.EmitMessage = function (websocketMessage) {
        this.conn.send(websocketMessage);
    };
    // Emit sends a custom websocket message
    Ws.prototype.Emit = function (event, data) {
        var messageStr = this.encodeMessage(event, data);
        this.EmitMessage(messageStr);
    };
    return Ws;
}());
`)

ClientSource the client-side javascript raw source code.

View Source 
var (
	// DefaultIDGenerator returns a random unique for a new connection.
	// Used when config.IDGenerator is nil.
	DefaultIDGenerator = func(w http.ResponseWriter, r *http.Request) string {
		id, err := uuid.NewV4()
		if err != nil {
			return randomString(64)
		}
		return id.String()
	}
)
View Source 
var ErrAlreadyDisconnected = errors.New("already disconnected")

ErrAlreadyDisconnected can be reported on the `Connection#Disconnect` function whenever the caller tries to close the connection when it is already closed by the client or the caller previously.

Functions

func ClientHandler added in v0.2.0 

func ClientHandler(w http.ResponseWriter, r *http.Request)

ClientHandler is the handler which serves the javascript client-side. It can be used as an alternative of a custom http route to register the client-side javascript code, Use the Server's `ClientSource` field instead to serve the custom code if you changed the default prefix for custom websocket events.

Types

type Config 

type Config struct {
	// IDGenerator used to create (and later on, set)
	// an ID for each incoming websocket connections (clients).
	// The request is an input parameter which you can use to generate the ID (from headers for example).
	// If empty then the ID is generated by DefaultIDGenerator: uuid or,if failed, a randomString(64)
	IDGenerator func(w http.ResponseWriter, r *http.Request) string
	// EvtMessagePrefix is the prefix of the underline websocket events that are being established under the hoods.
	// This prefix is visible only to the javascript side (code) and it has nothing to do
	// with the message that the end-user receives.
	// Do not change it unless it is absolutely necessary.
	//
	// If empty then defaults to []byte("go-websocket-message:").
	EvtMessagePrefix []byte
	// Error is the function that will be fired if any client couldn't upgrade the HTTP connection
	// to a websocket connection, a handshake error.
	Error func(w http.ResponseWriter, r *http.Request, status int, reason error)
	// CheckOrigin a function that is called right before the handshake,
	// if returns false then that client is not allowed to connect with the websocket server.
	CheckOrigin func(r *http.Request) bool
	// HandshakeTimeout specifies the duration for the handshake to complete.
	HandshakeTimeout time.Duration
	// WriteTimeout time allowed to write a message to the connection.
	// 0 means no timeout.
	// Default value is 0
	WriteTimeout time.Duration
	// ReadTimeout time allowed to read a message from the connection.
	// 0 means no timeout.
	// Default value is 0
	ReadTimeout time.Duration
	// PongTimeout allowed to read the next pong message from the connection.
	// Default value is 60 * time.Second
	PongTimeout time.Duration
	// PingPeriod send ping messages to the connection within this period. Must be less than PongTimeout.
	// Default value is 60 *time.Second
	PingPeriod time.Duration
	// MaxMessageSize max message size allowed from connection.
	// Default value is 1024
	MaxMessageSize int64
	// BinaryMessages set it to true in order to denotes binary data messages instead of utf-8 text
	// compatible if you wanna use the Connection's EmitMessage to send a custom binary data to the client, like a native server-client communication.
	// Default value is false
	BinaryMessages bool
	// ReadBufferSize is the buffer size for the connection reader.
	// Default value is 4096
	ReadBufferSize int
	// WriteBufferSize is the buffer size for the connection writer.
	// Default value is 4096
	WriteBufferSize int
	// EnableCompression specify if the server should attempt to negotiate per
	// message compression (RFC 7692). Setting this value to true does not
	// guarantee that compression will be supported. Currently only "no context
	// takeover" modes are supported.
	//
	// Defaults to false and it should be remain as it is, unless special requirements.
	EnableCompression bool

	// Subprotocols specifies the server's supported protocols in order of
	// preference. If this field is set, then the Upgrade method negotiates a
	// subprotocol by selecting the first match in this list with a protocol
	// requested by the client.
	Subprotocols []string
}

Config the websocket server configuration all of these are optional.

func (Config) Validate 

func (c Config) Validate() Config

Validate validates the configuration

type Connection 

type Connection interface {
	// Emitter implements EmitMessage & Emit
	Emitter
	// Err is not nil if the upgrader failed to upgrade http to websocket connection.
	Err() error

	// ID returns the connection's identifier
	ID() string

	// Request returns the http.Request ptr of the original http
	// request.
	Request() *http.Request
	// Server returns the websocket server instance
	// which this connection is listening to.
	//
	// Its connection-relative operations are safe for use.
	Server() *Server

	// Write writes a raw websocket message with a specific type to the client
	// used by ping messages and any CloseMessage types.
	Write(websocketMessageType int, data []byte) error

	// OnDisconnect registers a callback which is fired when this connection is closed by an error or manual
	OnDisconnect(DisconnectFunc)
	// OnError registers a callback which fires when this connection occurs an error
	OnError(ErrorFunc)
	// OnPing  registers a callback which fires on each ping
	OnPing(PingFunc)
	// OnPong  registers a callback which fires on pong message received
	OnPong(PongFunc)
	// FireOnError can be used to send a custom error message to the connection
	//
	// It does nothing more than firing the OnError listeners. It doesn't send anything to the client.
	FireOnError(err error)
	// To defines on what "room" (see Join) the server should send a message
	// returns an Emmiter(`EmitMessage` & `Emit`) to send messages.
	To(string) Emitter
	// OnMessage registers a callback which fires when native websocket message received
	OnMessage(NativeMessageFunc)
	// On registers a callback to a particular event which is fired when a message to this event is received
	On(string, MessageFunc)
	// Join registers this connection to a room, if it doesn't exist then it creates a new. One room can have one or more connections. One connection can be joined to many rooms. All connections are joined to a room specified by their `ID` automatically.
	Join(string)
	// IsJoined returns true when this connection is joined to the room, otherwise false.
	// It Takes the room name as its input parameter.
	IsJoined(roomName string) bool
	// Leave removes this connection entry from a room
	// Returns true if the connection has actually left from the particular room.
	Leave(string) bool
	// OnLeave registers a callback which fires when this connection left from any joined room.
	// This callback is called automatically on Disconnected client, because websocket server automatically
	// deletes the disconnected connection from any joined rooms.
	//
	// Note: the callback(s) called right before the server deletes the connection from the room
	// so the connection theoretical can still send messages to its room right before it is being disconnected.
	OnLeave(roomLeaveCb LeaveRoomFunc)
	// Wait starts the pinger and the messages reader,
	// it's named as "Wait" because it should be called LAST,
	// after the "On" events IF server's `Upgrade` is used,
	// otherise you don't have to call it because the `Handler()` does it automatically.
	Wait()
	// Disconnect disconnects the client, close the underline websocket conn and removes it from the conn list
	// returns the error, if any, from the underline connection
	Disconnect() error
	// SetValue sets a key-value pair on the connection's mem store.
	SetValue(key string, value interface{})
	// GetValue gets a value by its key from the connection's mem store.
	GetValue(key string) interface{}
	// GetValueArrString gets a value as []string by its key from the connection's mem store.
	GetValueArrString(key string) []string
	// GetValueString gets a value as string by its key from the connection's mem store.
	GetValueString(key string) string
	// GetValueInt gets a value as integer by its key from the connection's mem store.
	GetValueInt(key string) int
}

Connection is the front-end API that you will use to communicate with the client side

type ConnectionFunc 

type ConnectionFunc func(Connection)

ConnectionFunc is the callback which fires when a client/connection is connected to the Server. Receives one parameter which is the Connection

type ConnectionValues added in v0.2.0 

type ConnectionValues []connectionValue

ConnectionValues is the temporary connection's memory store

func (*ConnectionValues) Get added in v0.2.0 

func (r *ConnectionValues) Get(key string) interface{}

Get returns a value based on its key

func (*ConnectionValues) Reset added in v0.2.0 

func (r *ConnectionValues) Reset()

Reset clears the values

func (*ConnectionValues) Set added in v0.2.0 

func (r *ConnectionValues) Set(key string, value interface{})

Set sets a value based on the key

type DisconnectFunc 

type DisconnectFunc func()

DisconnectFunc is the callback which is fired when a client/connection closed

type Emitter added in v0.0.3 

type Emitter interface {
	// EmitMessage sends a native websocket message
	EmitMessage([]byte) error
	// Emit sends a message on a particular event
	Emit(string, interface{}) error
}

Emitter is the message/or/event manager

type ErrorFunc 

type ErrorFunc (func(error))

ErrorFunc is the callback which fires whenever an error occurs

type LeaveRoomFunc added in v0.2.0 

type LeaveRoomFunc func(roomName string)

LeaveRoomFunc is the callback which is fired when a client/connection leaves from any room. This is called automatically when client/connection disconnected (because websocket server automatically leaves from all joined rooms)

type MessageFunc 

type MessageFunc interface{}

MessageFunc is the second argument to the Emitter's Emit functions. A callback which should receives one parameter of type string, int, bool or any valid JSON/Go struct

type NativeMessageFunc 

type NativeMessageFunc func([]byte)

NativeMessageFunc is the callback for native websocket messages, receives one []byte parameter which is the raw client's message

type PingFunc added in v0.2.0 

type PingFunc func()

PingFunc is the callback which fires each ping

type PongFunc added in v0.2.0 

type PongFunc func()

PongFunc is the callback which fires on pong message received

type Server 

type Server struct {

	// ClientSource contains the javascript side code
	// for the websocket communication
	// based on the configuration's `EvtMessagePrefix`.
	//
	// Use a route to serve this file on a specific path, i.e
	// mux.HandleFUNC("/go-websocket.js", func(w http.ResponseWriter, _ *http.Request) { w.Write(mywebsocketServer.ClientSource) })
	ClientSource []byte
	// contains filtered or unexported fields
}

Server is the websocket Server's implementation.

It listens for websocket clients (either from the javascript client-side or from any websocket implementation). See `OnConnection` , to register a single event which will handle all incoming connections and the `Handler` which builds the upgrader handler that you can register to a route based on an Endpoint.

To serve the built'n javascript client-side library look the `websocket.ClientHandler`.

func New 

func New(cfg Config) *Server

New returns a new websocket Server based on a configuration. See `OnConnection` , to register a single event which will handle all incoming connections and the `Handler` which builds the upgrader handler that you can register to a route based on an Endpoint.

To serve the built'n javascript client-side library look the `websocket.ClientHandler`.

func (*Server) Disconnect added in v0.0.3 

func (s *Server) Disconnect(connID string) (err error)

Disconnect force-disconnects a websocket connection based on its connection.ID() What it does? 1. remove the connection from the list 2. leave from all joined rooms 3. fire the disconnect callbacks, if any 4. close the underline connection and return its error, if any.

You can use the connection.Disconnect() instead.

func (*Server) GetConnection added in v0.2.0 

func (s *Server) GetConnection(connID string) Connection

GetConnection returns single connection

func (*Server) GetConnections added in v0.2.0 

func (s *Server) GetConnections() []Connection

GetConnections returns all connections

func (*Server) GetConnectionsByRoom added in v0.2.0 

func (s *Server) GetConnectionsByRoom(roomName string) []Connection

GetConnectionsByRoom returns a list of Connection which are joined to this room.

func (*Server) GetTotalConnections added in v0.2.0 

func (s *Server) GetTotalConnections() (n int)

GetTotalConnections returns the number of total connections

func (*Server) Handler 

func (s *Server) Handler(w http.ResponseWriter, r *http.Request)

Handler is the websocket handler which registers the endpoint's handler and fires the events to the registered `OnConnection` event. It should be called once per Server, its result should be passed as a route handler to register the websocket's endpoint.

Endpoint is the path which the websocket Server will listen for clients/connections.

To serve the built'n javascript client-side library look the `websocket.ClientHandler`. This handles any websocket error, use the `Upgrade` for custom error reporting and connection handling.

func (*Server) IsConnected added in v0.0.3 

func (s *Server) IsConnected(connID string) bool

IsConnected returns true if the connection with that ID is connected to the Server useful when you have defined a custom connection id generator (based on a database) and you want to check if that connection is already connected (on multiple tabs)

func (*Server) IsJoined added in v0.2.0 

func (s *Server) IsJoined(roomName string, connID string) bool

IsJoined reports if a specific room has a specific connection into its values. First parameter is the room name, second is the connection's id.

It returns true when the "connID" is joined to the "roomName".

func (*Server) Join added in v0.0.3 

func (s *Server) Join(roomName string, connID string)

Join joins a websocket client to a room, first parameter is the room name and the second the connection.ID()

You can use connection.Join("room name") instead.

func (*Server) Leave added in v0.0.3 

func (s *Server) Leave(roomName string, connID string) bool

Leave leaves a websocket client from a room, first parameter is the room name and the second the connection.ID()

You can use connection.Leave("room name") instead. Returns true if the connection has actually left from the particular room.

func (*Server) LeaveAll added in v0.0.3 

func (s *Server) LeaveAll(connID string)

LeaveAll kicks out a connection from ALL of its joined rooms

func (*Server) OnConnection 

func (s *Server) OnConnection(cb ConnectionFunc)

OnConnection is the main event you, as developer, will work with each of the websocket connections.

func (*Server) Upgrade added in v0.2.0 

func (s *Server) Upgrade(w http.ResponseWriter, r *http.Request) Connection

Upgrade upgrades the HTTP Server connection to the WebSocket protocol.

The responseHeader is included in the response to the client's upgrade request. Use the responseHeader to specify cookies (Set-Cookie) and the application negotiated subprotocol (Sec--Protocol).

If the upgrade fails, then Upgrade replies to the client with an HTTP error response and the return `Connection.Err()` is filled with that error.

For a more high-level function use the `Handler()` and `OnConnecton` events. This one does not starts the connection's writer and reader, so after your `On/OnMessage` events registration the caller has to call the `Connection#Wait` function, otherwise the connection will be not handled.

Caller should handle the error based on the connection's Err().

type UnderlineConnection 

type UnderlineConnection interface {
	// SetWriteDeadline sets the write deadline on the underlying network
	// connection. After a write has timed out, the websocket state is corrupt and
	// all future writes will return an error. A zero value for t means writes will
	// not time out.
	SetWriteDeadline(t time.Time) error
	// SetReadDeadline sets the read deadline on the underlying network connection.
	// After a read has timed out, the websocket connection state is corrupt and
	// all future reads will return an error. A zero value for t means reads will
	// not time out.
	SetReadDeadline(t time.Time) error
	// SetReadLimit sets the maximum size for a message read from the peer. If a
	// message exceeds the limit, the connection sends a close frame to the peer
	// and returns ErrReadLimit to the application.
	SetReadLimit(limit int64)
	// SetPongHandler sets the handler for pong messages received from the peer.
	// The appData argument to h is the PONG frame application data. The default
	// pong handler does nothing.
	SetPongHandler(h func(appData string) error)
	// SetPingHandler sets the handler for ping messages received from the peer.
	// The appData argument to h is the PING frame application data. The default
	// ping handler sends a pong to the peer.
	SetPingHandler(h func(appData string) error)
	// WriteControl writes a control message with the given deadline. The allowed
	// message types are CloseMessage, PingMessage and PongMessage.
	WriteControl(messageType int, data []byte, deadline time.Time) error
	// WriteMessage is a helper method for getting a writer using NextWriter,
	// writing the message and closing the writer.
	WriteMessage(messageType int, data []byte) error
	// ReadMessage is a helper method for getting a reader using NextReader and
	// reading from that reader to a buffer.
	ReadMessage() (messageType int, p []byte, err error)
	// NextWriter returns a writer for the next message to send. The writer's Close
	// method flushes the complete message to the network.
	//
	// There can be at most one open writer on a connection. NextWriter closes the
	// previous writer if the application has not already done so.
	NextWriter(messageType int) (io.WriteCloser, error)
	// Close closes the underlying network connection without sending or waiting for a close frame.
	Close() error
}

UnderlineConnection is the underline connection, nothing to think about, it's used internally mostly but can be used for extreme cases with other libraries.

Source Files

View all Source files

Directories

Path Synopsis
_examples
chat

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.