Groups

gox.Groups consult and manage the active WebSocket groups known for the runtime.

members := gox.Groups.Members("administrators")
members.Emit("permissionsUpdated")

The groups are ephemeral: they exist while containing at least one socket.

Structure

Groups
{
    List() []string
    Has(group string) bool
    Count() int
    Members(group string) gox.SocketCollection
    CountMembers(group string) int
    EmitTo(group string, event string, values ...any)
}

Methods

List()

Firma:func (*GroupRegistry) List() []string

Returns a snapshot of the names of active groups.

for _, group := range gox.Groups.List() {
    log.Println(group)
}

The returned slice is an independent copy. A group can disappear after creating the snapshot.

Has()

Firma:func (*GroupRegistry) Has(group string) bool

It indicates whether the name is valid and the group contains at least one member.

if gox.Groups.Has("administrators") {
    log.Println("Group active")
}

An invalid name returns false.

Count()

Firma:func (*GroupRegistry) Count() int

Returns the number of active groups.

total := gox.Groups.Count()

Members()

Firma:func (*GroupRegistry) Members(group string) gox.SocketCollection

Returns a dynamic collection with the group's sockets.

members := gox.Groups.Members("administrators")
members.Emit("permissionsUpdated")

Each operation resolves the current members. A non-existent or invalid group produces a valid and empty collection.

To know All(), Count(), Emit() and Disconnect(), consultation SocketCollection.

CountMembers()

Firma:func (*GroupRegistry) CountMembers(group string) int

Returns the number of sockets that belong to the group at that time.

connected := gox.Groups.CountMembers("administrators")

A non-existing group or invalid name returns 0.

EmitTo()

Firma:func (*GroupRegistry) EmitTo(group string, event string, values ...any)

It emits an event to all the current members of the group.

gox.Groups.EmitTo("administrators", "serverUpdated", true)

An invalid group name or an empty event does not produce any emissions. When a cluster exists, the event is automatically distributed.

To learn the format of events and values, visit WebSocket events.

Naming rules

The names are sensitive to capital and lowercase and GOX does not normalize them. They must comply with these rules:

• They can't be empty.
• They can't get over 128 bytes.
• They must contain valid UTF-8.
• They can't start or end with spaces.
• They cannot contain control characters.

administrators and Administrators They represent different groups.

Methods Join() and Leave() return an error when the name is invalid. To know the administration of membranes from each socket, visit WebSocket Groups.

Distributed scope

With an active adapter, List(), Count(), Members(), CountMembers() and EmitTo() represent the overall directory of the project.

To learn how to enable this behavior, visit Cluster configuration.

Integration with Go

The snapshots are represented by []string and membranes by gox.SocketCollection. The names are preserved exactly as the API receives them.

Byte validation means that UTF-8 characters of several bytes consume more than one position of the limit of 128 bytes.

Best practices

• Define a stable convention for names.
• It retains the names already validated instead of reconstructing them repeatedly.
• Use Members().Emit() or EmitTo() for collective emissions.
• Do not assume that a group will continue to exist after Has().
• Avoid including sensitive data directly in the name of the group.

See also

• SocketCollection
• WebSocket events
• WebSocket Groups
• Cluster configuration