Lifecycle

GOX automatically manages the creation, recovery and persistence of sessions.

When a client makes a request, GOX uses session cookies to recover its current session. If there is no valid session, create a new one and send your credentials to the client.

func Login(ctx *gox.Context) gox.Action {
    if err := ctx.Session.Set("userID", "usr_123"); err != nil {
        return ctx.Response.DoneWith(500)
    }

    if err := ctx.Session.Rotate(); err != nil {
        return ctx.Response.DoneWith(500)
    }

    return ctx.Response.DoneWith(204)
}

Rotate() must be used after authenticating the user or changing his privileges to replace the current token without losing the session.

Structure

ctx.Session provides the following methods related to your life cycle:

Session
{
    ID() string
    Token() string
    Rotate() error
    Destroy() error
    IsDestroyed() bool
}

ID() and Token() allow the identity automatically administered by GOX to be consulted.

Methods

ID()

Firma:func (*Session) ID() string

ID() return the session identifier.

sessionID := ctx.Session.ID()

The identifier remains the same throughout the session life, even after running Rotate().

A new session receives a different identifier.

Token()

Firma:func (*Session) Token() string

Token() return the current session token.

sessionToken := ctx.Session.Token()

GOX uses this value together with the identifier to validate that the client can access the session.

The token changes when running Rotate().

Rotate()

Firma:func (*Session) Rotate() error

Rotate() generates a new token without changing the identifier or the values stored in the session.

func Login(ctx *gox.Context) gox.Action {
    if err := ctx.Session.Set("authenticated", true); err != nil {
        return ctx.Response.DoneWith(500)
    }

    if err := ctx.Session.Rotate(); err != nil {
        return ctx.Response.DoneWith(500)
    }

    return ctx.Response.DoneWith(204)
}

GOX automatically updates the cookie that contains the token.

previousID := ctx.Session.ID()
previousToken := ctx.Session.Token()

if err := ctx.Session.Rotate(); err != nil {
    return ctx.Response.DoneWith(500)
}

// ctx.Session.ID() == previousID
// ctx.Session.Token() != previousToken

Use Rotate() after authenticating the user or modifying its privileges.

The rotation needs the HTTP response to send the new token to the client. For this reason, it is available during Page and Action, but not from a session preserved by WebSocket.

Destroy()

Firma:func (*Session) Destroy() error

Destroy() permanently eliminates the session.

func Logout(ctx *gox.Context) gox.Action {
    if err := ctx.Session.Destroy(); err != nil {
        return ctx.Response.DoneWith(500)
    }

    return ctx.Response.DoneWith(204)
}

When run during an HTTP request, GOX also eliminates client session cookies.

After destroying the session:

• Their values are no longer available.
• No new values can be stored.
• Rotate() Stop being available.
• IsDestroyed() return true.

WebSocket connections associated with the session also close when they receive the destruction notification.

Destroy() It is idempowerful. Run it again on the same destroyed session does not try to remove it again or produce an additional error.

To remove only the stored values and keep the active session, use Clear(). Consultation Session Storage to know that operation.

IsDestroyed()

Firma:func (*Session) IsDestroyed() bool

IsDestroyed() indicates whether the session was explicitly destroyed.

if ctx.Session.IsDestroyed() {
    return ctx.Response.DoneWith(401)
}

After running Destroy(), return. true.

if err := ctx.Session.Destroy(); err != nil {
    return ctx.Response.DoneWith(500)
}

// ctx.Session.IsDestroyed() == true

The state of destruction is shared between the HTTP and WebSocket representations of the same session.

IsDestroyed() does not indicate whether a session expired by inactivity. The expiry belongs to the behaviour of the TTL.

Creation and retrieval

GOX resolves the session before running Page, Action or setting up a WebSocket connection.

If the credentials received identify a valid session, GOX recovers that session along with its values.

GOX creates a new session when:

• The client does not have a session yet.
• There is no such session.
• The token received is not valid.
• The previous session expired.

The new session receives an identifier and a token, and GOX sends both values to the client using HTTP cookies.

It is not necessary to create sessions, generate identifiers or manage these cookies manually.

The sessions expire when they remain inactive during the set-up time. TTL to know the duration and renewal of a session.

Full example

The following example authenticates the user, breaks the token and then destroys the session by closing the session:

func Login(ctx *gox.Context) gox.Action {
    if err := ctx.Session.Set("userID", "usr_123"); err != nil {
        return ctx.Response.DoneWith(500)
    }

    if err := ctx.Session.Rotate(); err != nil {
        return ctx.Response.DoneWith(500)
    }

    return ctx.Response.DoneWith(204)
}

func Logout(ctx *gox.Context) gox.Action {
    if err := ctx.Session.Destroy(); err != nil {
        return ctx.Response.DoneWith(500)
    }

    return ctx.Response.DoneWith(204)
}

Rotation retains the stored values. Destruction eliminates the complete session.

Best practices

• Use Rotate() after authenticating a user or changing its privileges.
• Use Destroy() when the user closes the session.
• Check the errors returned by Rotate() and Destroy().
• Use Clear() when you need to remove the values without destroying the session.
• Do not use IsDestroyed() to check if a session expired.
• It allows GOX to manage cookies and session credentials.

See also

• Session Storage
• TTL