Cluster

The field Cluster accepts a server.ClusterAdapterWith. nil, GOX runs a single instance and keeps sessions in local memory.

The field is assigned in the root structure described in Configuration.

Cluster: nil,

To run several instances, it uses a shared adapter. The Redis Adapter distributes sessions and coordinates sockets, groups and channels between instances.

Install Redis Adapter

From the root of the project, add the module:

go get github.com/gox-lang/cluster/redisadapter

You also need a Redis instance accessible by all GOX instances.

Configure the adapter

It matters. redisadapter from app/config.gox and assigns the result of redisadapter.New() a Cluster:

module app

import (
    "time"
    "github.com/gox-lang/cluster/redisadapter"
    "github.com/gox-lang/gox/server"
    "http.gox"
    "ratelimit.gox"
    "routes.gox"
    "session.gox"
    "static.gox"
    "websocket.gox"
)

func SetGoxConfig() server.Config {
    return server.Config{
        ProjectName: "hello",

        Cluster: redisadapter.New(redisadapter.Config{
            Name: "production",
            Host: "127.0.0.1:6379",
            DB:   0,

            PoolSizeIdle: 4,
            PoolSizeMax:  32,

            CleanupInterval:  time.Hour,
            InstanceLeaseTTL: 15 * time.Second,
            InstanceHeartbeat: 5 * time.Second,

            Auth: redisadapter.RedisAuthConfig{
                Username: "",
                Password: "",
            },
        }),

        HTTP:      http.Config,
        RateLimit: ratelimit.Config,
        Session:   session.Config,
        Static:    static.Config,
        Routes:    routes.Config,
        WebSocket: websocket.Config,
    }
}

Host use the format host:port. Name identifies the cluster; if it is empty, the adapter uses redis. DB, authentication, pool and times belong to the adapter, not to server.Config.

Do not include credentials directly in the repository. Build the configuration from the secret mechanism used by your deployment.

Distributed behavior

With the active adapter:

• The sessions can be opened from any instance.
• The destruction and expiry of sessions are notified between instances.
• WebSocket can locate remote sockets.
• Emissions, disconnections, groups and channels are coordinated by Redis.

See Sessions to set up TTL and events, and WebSocket for the limits applied to the connections.

All instances of the same deployment must use the same ProjectName, the same cluster name and a compatible configuration.

Hot reload

When changing Cluster, GOX tries to open the new adapter before replacing the previous runtime. If the connection or validation fails, it retains the previous configuration.

When the replacement is successful, subsequent distributed sessions and operations use the new adapter and GOX closes the previous. WebSocket connections already open continue their own life cycle; it avoids changing backend during active traffic without planning the transition.

Best practices

• Use nil where there is only one instance.
• Use the same ProjectName and Name in all related instances.
• Check for connectivity and authentication of Redis before deployment.
• Configure a pool in line with the expected concurrence.
• Keep InstanceHeartbeat below InstanceLeaseTTL.
• You don't store credentials in versioned files.
• It oversees latency, connections and memory of Redis.

See also

• Configuration
• Sessions
• WebSocket