socket

README

go-socket

A simple way to manage many WebSocket clients

With this package each connected client recieves a unique short ID. It is possible to Send or Broadcast to all the connected clients. There is no concepts of rooms or lobbies with this package.

All messages received must conform as a Message structure:

type Message struct {
	From    string      `json:"-"`
	Type    string      `json:"type"`
	Payload interface{} `json:"payload"`
}

Message.From is assigned by the package to identify who the message is from, it is never shared with clients. Message.Type is assigned by you so you can differentiate message types. Message.Payload is the actual data payload for the message.

I wrote this package to help facilitate some projects I'm working on. They are primarily used to communicate a React client (browser) with the server (golang).

Here's a quick example of working with received messages.

msg := <-socket.Read()
switch msg.Type {
    case "ADD_TO_QUEUE":
        if id, ok := msg.Payload.(string); ok {
            // do something with id
        } else {
            // let the client know their request was bad
            socket.Send(msg.From, "ERROR", "you did not provide a valid id!")
        }
}

The benefit of having Payload being interface{} is that your client can push anything, including JSON, and you can test for it on the fly.

if data, ok := msg.Payload.(map[string]interface{}); ok {
    if name, ok := data["name"].(string); ok {
        // now we know the client's name
    }
    if age, ok := data["age"].(int); ok {
        // and their age
    }
}

As my other personal projects grow with complexity this package might do the same. I definitely see an advantage of having lobbies/rooms/hubs/etc, as a way to partition clients into groups. But until then...

Documentation

Index

• Variables
• func Broadcast(msgType string, msgPayload interface{}) error
• func Handler(w http.ResponseWriter, r *http.Request)
• func Send(clientID, msgType string, msgPayload interface{}) error
• type Message
  • func Read() *Message

Variables

var (

	// OnOpen is called whenever a new client is connected
	OnOpen func(clientID string)
	// OnClose is called whenever a client disconnects for any reason
	OnClose func(clientID string)
	// OnError is called whenever an error occurs
	OnError func(clientID string, err error)
	// CheckOrigin is used by Socket when upgrading a WebSocket connection
	CheckOrigin func(r *http.Request) bool
)

Functions

func Broadcast

func Broadcast(msgType string, msgPayload interface{}) error

Broadcast to all connected clients

func Handler

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

Handler connects a new client. Any errors are sent to the OnError callback or are instead sent to standard output.

func Send

func Send(clientID, msgType string, msgPayload interface{}) error

Send a message to a specific client by ID

Types

type Message

type Message struct {
	From    string      `json:"-"`
	Type    string      `json:"type"`
	Payload interface{} `json:"payload"`
}

Message that is received from connected clients

func Read

func Read() *Message

Read and block for the next available Message