MagicSockets
MagicSockets is a simple yet powerful WebSocket library for Go that makes it easy to manage client connections, emit messages based on rules, and handle incoming and outgoing messages.
Features
- Easy management of WebSocket client connections.
- Key-based and topic-based client identification.
- Emit messages to clients using rules for keys and topics.
- Receive incoming messages and send outgoing messages through custom handlers.
- Register and update client information easily.
Installation
To install MagicSockets, use the following command:
go get -u github.com/problem-company-toolkit/magicsockets
Usage
Starting the MagicSocket server
import (
"github.com/problem-company-toolkit/magicsockets"
)
func main() {
ms := magicsockets.New(magicsockets.MagicSocketOpts{
Port: 8080,
})
ms.Start() // Blocking
}
Connecting clients
To connect a client to the MagicSocket server, simply initiate a standard WebSocket connection, like so:
const socket = new WebSocket("ws://localhost:8080");
Emitting messages to clients
The following will only send messages to clients that match all rules:
ms.Emit(magicsockets.EmitOpts{
Rules: []magicsockets.EmitRule{
{
Keys: []string{"clientKey1", "clientKey2"},
},
{
Topics: []string{"topic1", "topic2"},
},
},
}, []byte("Hello, clients!"))
Registering a websocket connection
MagicSockets allows you to set an OnConnect
function, which handles how clients will be updated.
You can update this hook function after the server has already started, but clients will not be updated retroactively.
In this hook, you can define other hooks for when messages are received, sent, clients are connected, disconnected, etc.
ms.SetOnConnect(func(r *http.Request) (magicsockets.RegisterClientOpts, error) {
return magicsockets.RegisterClientOpts{
Key: "clientKey",
Topics: []string{"topic1", "topic2"},
OnIncoming: func(messageType int, data []byte) error {
fmt.Printf("Received message: %s\n", string(data))
return nil
},
OnOutgoing: func(messageType int, data []byte) error {
fmt.Printf("Sending message: %s\n", string(data))
return nil
},
}, nil
})
MagicSockets support updating the abstract "client" that is connecting to the server.
This way, you can have a single WebSocket connection, but change its identifier and topics according to your application's logic, without making any changes to the underlying WebSocket connection.
client := ms.GetClients()["clientKey"]
// Update client key
client.UpdateKey("newClientKey")
// Update client topics
client.SetTopics([]string{"newTopic1", "newTopic2"})
Situations where you might want to use this:
- Establishing one WebSocket connection per user.
- By manipulating the client key, you could set it to the user's ID once you receive an event that identifies the user.
- Subscribing or unsubscribing the user whenever they engage or stop certain activities within the same domain.
- This is particularly useful if you're using a PubSub solution. You can easily translate the concept of
topics
by simply syncing consuming events and producing events with your current messaging broker.
Configuring logger using environment variable
Set the log level using the environment variable MAGICSOCKETS_LOG_LEVEL
. Supported log levels are:
debug
info
warn
fatal
panic
dpanic
If an invalid log level is provided, the default log level (WarnLevel
) will be used.
The package uses a default log level of WarnLevel
and a default log encoding of console
.
If the log level is set to debug
, then the server will output when it's emitting messages, closing clients, receiving and sending messages (including the contents of the messages), etc.
Testing
To run the tests, execute the following command in the terminal:
ginkgo