Session

ctx.Session represents the session associated with the current client.

A session allows you to keep information between different requests from the same client, such as your user identifier, preferences, language or authentication status.

gox

func GET(ctx *gox.Context) gox.Page {
    var name string

    if exists, err := ctx.Session.Get("name", &name); err != nil || !exists {
        return ctx.Response.DoneWith(403)
    }

    return <p>Hola, {{ name }}</p>
}

GOX automatically creates and recovers the session. You do not need to read your cookies, generate identifiers or manually initialize it.

The same session API is available on Page, Action and WebSocket. The values stored by ctx.Session can be shared between these contexts as long as they belong to the same session.

Methods

Method	Description
`ID()`	Returns the session identifier.
`Token()`	Returns the current session token.
`Get(key, out)`	Read a stored value.
`Set(key, value)`	It stores a value.
`Has(key)`	It indicates if there is a key.
`GetAll()`	Returns all stored values.
`Delete(key)`	It eliminates a value.
`Clear()`	Eliminate all values without destroying the session.
`Rotate()`	Replace the session token.
`Destroy()`	It permanently destroys the session.
`IsDestroyed()`	It indicates whether the session was destroyed.
`SetTTL(ttl)`	Change the configured TTL.
`GetTTL()`	Returns the configured TTL.

Session Storage

Session Storage allows you to store values associated with a specific client's session.

Methods Get(), Set(), Has(), GetAll(), Delete() and Clear() allow to save, consult and remove these values.

gox

if err := ctx.Session.Set("language", "es"); err != nil {
    return ctx.Response.DoneWith(500)
}

var language string

if exists, err := ctx.Session.Get("language", &language); err != nil || !exists {
    return ctx.Response.DoneWith(403)
}

The changes remain available during the following requests associated with the same session.

See Session Storage to know the available transactions, the types of values that can be stored and the behaviour of Get().

Identity and lifecycle

Each session contains an identifier and a token.

Method	Description
`ID()`	Returns the session identifier.
`Token()`	Returns the token that validates the client's access to the session.

Both values are read-only and GOX automatically manages them.

Rotate() replace the token without changing the session identifier. This operation is useful after authenticating a user or modifying its privileges.

Destroy() permanently removes the session, while IsDestroyed() allows to check if it was destroyed.

See Lifecycle to know how the sessions are created, recovered, rotated and destroyed.

TTL

The sessions use an TTL to determine how long they can stay inactive before they expire.

Each valid request renews its maturity using the TTL set for that session.

gox

ctx.Session.SetTTL(24 * time.Hour)

SetTTL() change the TTL of the session and GetTTL() This value represents the full duration, not the remaining time before expiry.

See TTL to know the operation of the expiry and automatic renewal.

Events

The session configuration allows you to record two events:

Event	Description
`OnCreate`	It runs after creating a new session.
`OnExpire`	It runs when a session expires by inactivity.

OnCreate receives a modified session and can be used to set initial values.

OnExpire receives a reading-only representation with the data and metadata that the session had before it was deleted.

See Events to know their configuration and the differences between Session and ExpireSession.

Persistence

GOX keeps the sessions in memory by default. You can also use an external adapter to share them between several instances of the server.

The API of ctx.Session remains the same regardless of the configured adapter.

See Cluster to learn how to set up shared sessions between several instances of the server.

Session Storage belongs to a specific client. To store shared information at server level that does not belong to a session, use gox.Server.Storage.

See Server Storage to know the server's shared storage system.

Distributed sessions

To share the sessions between various bodies of gox-server, set up a cluster by redisadapter.

This allows all instances to recover and manage the same sessions, regardless of which one meets each request.

See Cluster configuration to know how to set up sessions distributed with Redis.

Best practices

Save only the information necessary to identify the client and maintain his or her status.
Use Rotate() after authenticating a user or changing its privileges.
Use Clear() when you need to remove the values without destroying the session.
Use Destroy() to definitely close the session.
Check the errors returned by the operations that read or modify values.
Do not send the values of ID() or Token() within the content of the response.
Configure the TTL according to the sensitivity and expected duration of the session.
You don't depend on OnExpire for operations to be carried out immediately.
Use ctx.Session for information associated with a client and gox.Server.Storage for shared information at server level.

To learn more about Response, check your documentation.

Next step

Continue with Session Storage to learn how to store, consult and delete values from a session.

Sessions