Sockets

gox.Sockets provides access to the global register of active WebSocket connections.

socket, exists := gox.Sockets.GetByID(socketID)

When the cluster is active, the record includes local and remote representations.

Structure

Sockets
{
    All() []*gox.Socket
    Count() int
    GetByID(socketID string) (*gox.Socket, bool)
    FindBySessionID(sessionID string) gox.SocketCollection
    Emit(event string, values ...any)
    Disconnect(code gox.WSCloseCode)
}

Methods

All()

Firma:func (*SocketRegistry) All() []*gox.Socket

Returns a snapshot of all sockets connected at the time.

for _, socket := range gox.Sockets.All() {
    log.Printf("Socket: %s", socket.ID)
}

The returned slice is independent of the record and does not contain values nil. Modifying the slice does not change the recorded sockets. Its elements continue to represent live connections that can be disconnected after creating the snapshot.

Count()

Firma:func (*SocketRegistry) Count() int

Returns the number of active sockets known to the runtime.

connected := gox.Sockets.Count()

The result represents the time of the query and can change immediately.

GetByID()

Firma:func (*SocketRegistry) GetByID(socketID string) (*gox.Socket, bool)

It recovers an active socket using its identifier.

socket, exists := gox.Sockets.GetByID(socketID)
if !exists {
    return
}

socket.Emit("updated")

When the ID is empty or the socket no longer exists, it returns nil and false.

To know the fields and methods of the recovered object, visit the documentation of Socket.

FindBySessionID()

Firma:func (*SocketRegistry) FindBySessionID(sessionID string) gox.SocketCollection

Returns a dynamic collection with all sockets of the session.

sockets := gox.Sockets.FindBySessionID(sessionID)
sockets.Emit("profileUpdated")

Unlike socket.SiblingsAn empty ID produces a valid and empty collection.

The collection resolves its members every time an operation is run. Therefore, it can be kept briefly without freezing the list of connections.

See the reference to SocketCollection to know their methods and behaviour.

Emit()

Firma:func (*SocketRegistry) Emit(event string, values ...any)

It emits an event to all active sockets.

gox.Sockets.Emit("serverUpdated", "v2")

When a cluster exists, the operation is automatically distributed. Emit() does not return an error; distributed transport errors are delivered by gox.Cluster.When("error", ...).

To learn about the encoding and reception of events, visit WebSocket events.

Disconnect()

Firma:func (*SocketRegistry) Disconnect(code gox.WSCloseCode)

Disconnect all active sockets using the code indicated.

gox.Sockets.Disconnect(gox.WSClosePermanent)

The operation is also distributed when the cluster is active. The connections that appear after the operation is resolved are not part of that disconnection.

Distributed scope

Remote sockets keep their ID and the instance ID that keeps the connection. Emissions and disconnections do not require manually checking IsLocal().

To learn to set up several instances, visit Cluster configuration.

Integration with Go

All() returns a normal pointer slice to gox.Socket, GetByID() follows the pattern value, ok and FindBySessionID() returns an instance of gox.SocketCollection.

Snapshots avoid exposing the internal structure of the record, but do not turn the connections into immutable objects.

Best practices

• Use GetByID() When you know the exact identity of the socket.
• Use FindBySessionID() to operate on all devices of a session.
• Do not assume that a socket obtained by All() It's still connected.
• It prefers the operations of the gox.SocketCollection to manually travel its members.
• It uses the closing code that represents the real cause.
• Record the cluster errors when you distribute operations.

See also

• Socket
• SocketCollection
• WebSocket events
• Cluster configuration