Server

The Server APIs allow you to consult and manage resources that belong to the full runtime of gox-server, rather than limited to a specific request or connection.

From these it is possible to obtain information from the current instance, to retain shared values within the process, to recover existing sessions and to manage sockets, groups and active channels.

projectName := gox.Server.ProjectName()
activeSockets := gox.Sockets.Count()
activeChannels := gox.Channels.Count()

These APIs are available through the GOX main package:

import "github.com/gox-lang/gox"

Available APIs

Each API represents an independent server area and can be used from Pages, Actions, WebSocket or Go packages of the application.

Server

gox.Server provides information on the current body of gox-server.

projectName := gox.Server.ProjectName()
instanceID := gox.Server.InstanceID()
uptime := gox.Server.Uptime()
address := gox.Server.Address()

It allows to consult the name of the project, the identity and direction of the instance, its time of activity and the current environment. Information always corresponds to the current process, even when several instances are part of the same cluster.

See gox.Server to know all your methods.

Storage

gox.Storage retains shared values between requests and connections processed by the current instance.

gox.Storage.Set("maintenance", true)

var maintenance bool
exists, err := gox.Storage.Get("maintenance", &maintenance)

Storage is safe for concurrent use, but it belongs only to the current process. Its values are not shared by the cluster, do not survive a reboot and do not replace a persistent storage.

See gox.Storage to know your operations and type rules.

Sessions

gox.Sessions allows you to recover an existing session by your identifier.

session, err := gox.Sessions.Get(sessionID)
if err != nil {
    return ctx.Response.DoneWith(404)
}

The recovered session is a normal instance of gox.Session. When modified by gox.Sessions.Get()changes should be explicitly saved with Save(). Get() does not create a session when the identifier does not exist and does not renew its activity just by recovering it.

See gox.Sessions to know the recovery, modification, persistence and destruction of sessions.

To know the storage, TTL and the life cycle of a session, visit the documentation of Sessions.

Sockets

gox.Sockets represents all active WebSocket connections known by the runtime.

socket, exists := gox.Sockets.GetByID(socketID)
sockets := gox.Sockets.FindBySessionID(sessionID)
sockets.Emit("profileUpdated")

It allows you to consult connections, to issue events and to disconnect them together. When the cluster is active, it includes local connections and those held by other instances.

See gox.Sockets to know the global record and the operations of gox.SocketCollection.

To know the creation, events and life cycle of these connections, visit the documentation of WebSocket.

Groups

gox.Groups allows to consult and manage active WebSocket groups.

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

The groups are ephemeral and cease to exist when they no longer contain sockets. When the cluster is active, gox.Groups represents the groups known by all the bodies.

See gox.Groups to know your operations and the rules of group names.

Channels

gox.Channels allows to consult the active instances of WebSocket channels.

channel, exists := gox.Channels.Get(channelID)
if exists {
    channel.Emit("updated")
}

This API works with active instances, not with the stated definitions within the websocket/. When the cluster is enabled, the record includes the active channels of all instances.

See gox.Channels to know the identity and administration of the active channels.

Cluster

gox.Cluster provides information on the distributed adapter and allows to receive errors related to its operation.

gox.Cluster.When("error", func(err gox.ClusterError) {
    log.Printf("Error del clúster: %s", err.Error())
})

The APIs of sockets, groups and channels automatically distribute their operations when an active adapter exists.

See gox.Cluster to know your information, events and error structure.

To learn how to set up several instances and its distributed adapter, visit the documentation of Cluster configuration.

Scope of resources

Integration with Go

Server APIs are normal package values and types gox. They can be used from Pages, Actions, WebSocket handlers, auxiliary functions and internal application packages while the runtime is active.

Your results use regular types of Go, such as string, bool, time.Time, time.Duration, slices, pointers and errors. This allows you to integrate the information and the resources of the server in a familiar way for any developer with go experience.

Best practices

• Use gox.Storage only for local temporary status.
• Check the errors returned by gox.Sessions.Get() and Session.Save().
• Use the distributed APIs without depending on the physical location of your resources.
• It retains identifiers and recovers resources when you are going to use them.
• Register the event error of gox.Cluster when you use a distributed adapter.

See also

• WebSocket
• Sessions
• Cluster configuration