Sessions

server.SessionConfig establishes the TTL and records the events of creation and expiry of the sessions.

module session

import (
    "log"
    "time"
    "github.com/gox-lang/gox/server"
)

var Config = server.SessionConfig{
    TTL: 3 * time.Hour,

    OnCreate: func(session *server.Session) {
        if err := session.Set("language", "es"); err != nil {
            log.Printf("session %s: cannot set default language: %v", session.ID(), err)
        }

        if err := session.Set("theme", "light"); err != nil {
            log.Printf("session %s: cannot set default theme: %v", session.ID(), err)
        }
    },

    OnExpire: func(session *server.ExpireSession) {
        log.Printf("session expired: %s", session.ID())
    },
}

TTL

TTL is a time.Duration. When you keep your zero value, the runtime uses 3 hours.

TTL: 30 * time.Minute,

The HTTP and WebSocket activity renews the session's validity. TTL to learn about renewal and expiration.

OnCreate

OnCreate receives *server.Session every time GOX naturally creates a new session for a client.

OnCreate: func(session *server.Session) {
    if err := session.Set("onboarding", true); err != nil {
        log.Printf("cannot initialize session %s: %v", session.ID(), err)
    }
},

It is suitable for small initial values such as language, theme, region or onboarding status. Check each writing error. Avoid expensive external consultations because callback is part of the session creation.

Configured values are available from ctx.Session in Pages and Actions, and from socket.Session on WebSocket. Session Storage to read and modify those data.

OnExpire

OnExpire receives *server.ExpireSession when the storage notifies that a session expired.

OnExpire: func(session *server.ExpireSession) {
    log.Printf("expired session: %s", session.ID())
},

Use it for external data audit or cleaning. Do not try to revive the session from this callback.

The distributed behavior depends on the configured adapter. Cluster when several instances have to share sessions.

Storage

SessionConfig does not contain a field StorageWith. Cluster: nil, GOX uses the local memory adapter. By setting up a cluster, its runtime provides the shared storage of sessions.

Hot reload

The changes in TTL, OnCreate and OnExpire They apply to subsequent operations. During recharge, GOX reopens the local storage or the cluster adapter with the new policy and closes the previous one when the requests that still use it are finished. Each request retains its policy and storage until it is completed, even if the configuration is recharged while it is in progress. New requests use the new configuration.

OnCreate It does not run on existing sessions. A new TTL should not be interpreted as a manual migration of historical data; it applies when the runtime opens, creates or renews sessions according to the active backend.

If the new storage cannot be opened, GOX retains the above valid configuration.

Best practices

• It uses an TTL in accordance with the risk and activity of the application.
• It initiates only small and determinist values in OnCreate.
• Check the errors returned when writing initial values.
• Keep OnExpire fast and tolerant to reattempts.
• No secret stores or connection objects within a session.
• It uses a shared adapter when you run several instances.

See also

• TTL
• Session Storage
• Cluster