Sessions

gox.Sessions recover an existing session using your identifier without needing the cookies or the client's token.

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

The API does not create new sessions and does not renew the TTL just by consulting them.

Structure

gox.Sessions provides a single method:

Sessions
{
    Get(sessionID string) (*gox.Session, error)
}

Get() returns an instance of gox.Session. The operations carried out subsequently belong to the session recovered and not to gox.Sessions.

Methods

Get()

Firma:func (*SessionRegistry) Get(sessionID string) (*gox.Session, error)

Get() recovers the stored session under sessionID.

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

The identifier must correspond to an existing session. An empty string, a non-existing, expired or unavailable session produces an error and does not return a usable session.

Get() does not value the client's token because this API is intended for reliable server code. The application must check that the current user or process is authorized to operate on the given session.

Recovering a session does not renew your activity or extend your TTL.

Retrieved session

Get() returns a pointer to a normal instance of gox.Session:

*gox.Session

The session uses the same storage and life cycle as its available representations by ctx.Session and socket.Session.

Its fields and methods are not part of the facade gox.Sessions. They are used on the value returned by Get():

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

if err := session.Set("status", "active"); err != nil {
    return ctx.Response.DoneWith(500)
}

To know all fields, storage, TTL and the life cycle of gox.Session, visit the documentation of Sessions.

Modification and persistence

Methods Set(), Delete() and Clear() change the recovered session. These changes should be explicitly pursued by Session.Save().

If you change a session recovered by gox.Sessions.Get()You must always call Save() and check the returned error. Save(), changes made with Set(), Delete() or Clear() do not persist.

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

if err := session.Set("status", "active"); err != nil {
    return ctx.Response.DoneWith(500)
}

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

Save() belongs to gox.Sessionnot a gox.Sessions.

The sessions related to ctx.Session and socket.Session they maintain their automatic persistence. Manual persistence is necessary for a session recovered by gox.Sessions.Get() because there is no request or event whose end can be used to save your changes.

Group the necessary modifications and call for Save() once after the operation.

Destruction

A recovered session can be destroyed by Session.Destroy():

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

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

Destroy() belongs to gox.Session and immediately delete the session. No need to call Save() after you destroy it.

The destruction is communicated to HTTP and WebSocket representations associated with the same session.

Rotation

Session.Rotate() is not available on a session obtained by gox.Sessions.Get().

The rotation needs an HTTP response to send the new token to the client. Use it by ctx.Session during a Page or Action.

This limitation belongs to the context of the recovered session and does not represent a method of gox.Sessions.

TTL and lifecycle

Get() do not renew the TTL. The session may expire after recovery if the application retains the reference for too long.

The amendment and Save() nor should they be used as substitutes for the normal activity of an HTTP or WebSocket session.

To learn about the duration, renewal, destruction and rotation of sessions, visit the documentation of the Sessions.

Security

The identifier allows the server code to locate a session without checking the client's token. Do not accept a sessionID without validating that the current user is authorized to operate on that session.

Do not send the identifier or the session token within the content of a response.

When access to the session is part of a protected operation, it responds according to the authorization of that operation. A recovery failure does not in itself represent an existing HTTP route.

Integration with Go

Get() follow the explicit management of usual Go errors and return the same type gox.Session used in HTTP and WebSocket. The global facade only resolves the session; subsequent operations are executed directly on the returned value.

The manual persistence clearly delimits the operation: it modifies the necessary values, checks each error and calls for Save() once at the end.

Best practices

• Valid the authorization before you recover a session by your identifier.
• Check the error returned by Get() before using the session.
• Do not automatically interpret a Get() as a non-existent route.
• Do not keep references to sessions for long periods.
• Group the modifications and call Session.Save() at the end.
• Don't call Save() after Session.Destroy().
• Use Session.Rotate() only from an HTTP request.
• Do not confuse the methods of the recovered session with the methods of gox.Sessions.

See also

• Sessions