Sessions

Use sessions.Start() to start a session.

lib/handlers/welcome.go

package handlers

import (
    "github.com/razshare/frizzante/connections"
    "github.com/razshare/frizzante/sessions"
)

type State struct{
    Name string
}

func Welcome(con *connections.Connection) {
    session := sessions.Start(con, State{})
}

This will retrieve the user’s session or create a new one if none is found.

Note

The session is retrieved based on the user’s session-id cookie.

When session retrieval fails, sessions.Start() creates a new session instead and sends a new session-id cookie to the user.

Danger

Since sessions.Start() may send a cookie, it is important to remember that the order in which data is sent to the user matters.

Read more about order of operations.

Save

Use Save() to save the session state.

lib/handlers/welcome.go

package handlers

import (
    "github.com/razshare/frizzante/connections"
    "github.com/razshare/frizzante/sessions"
)

type State struct{
    Name string
}

func Welcome(con *connections.Connection) {
    session := sessions.Start(con, State{})
    defer session.Save()
    session.Name = "World"
}

Load

Use Load() to load the session state.

lib/handlers/welcome.go

package handlers

import (
    "github.com/razshare/frizzante/connections"
    "github.com/razshare/frizzante/sessions"
)

type State struct{
    Name string
}

func Welcome(con *connections.Connection) {
    session := sessions.Start(con, State{})
    session.Load()
    con.SendMessage("Hello " + session.State.Name)
}

Tip

Session state is automatically loaded when invoking sessions.Start().
Generally speaking you wouldn’t load the session state more than once per handler, but there are some cases where it can be useful to do so, for example when handling long running server sent events or web socket connections.

Destroy

Use Destroy() to destroy a session.

lib/handlers/welcome.go

package handlers

import (
    "github.com/razshare/frizzante/connections"
    "github.com/razshare/frizzante/sessions"
)

type State struct{
    Name string
}

func Welcome(con *connections.Connection) {
    session := sessions.Start(con, State{})
    session.Destroy()
}

Custom Archive

Sessions are managed through an Archive and you can overwrite the default Archive using sessions.WithArchive().

main.go

import "github.com/razshare/frizzante/sessions"

func main(){
    sessions.WithArchive(&CustomArchive{})
}

Where CustomArchive implements Archive.

type Archive interface {
    Get(domain string, key string) ([]byte, error)
    Set(domain string, key string, value []byte) error
    Has(domain string, key string) (bool, error)
    Remove(domain string, key string) error
    HasDomain(domain string) (bool, error)
    RemoveDomain(domain string) error
}

Archive Details

Think of an Archive as a repository of data separated in two layers; domains and keys.

An archive contains domains which contain keys.

• Directoryarchive

  • Directorydomain-1

    • key-a
    • key-b
  • Directorydomain-2

    • key-x
    • key-y

Default Archive

The default operator archive is backed by the file system, more specifically, by a .gen/sessions directory.

• Directory.gen

  • Directorysessions

    • Directory0d0d0c2f-6bb9-405f-6a41-d4fe9acf3dd2

      • session.json
    • Directory8a6d8cfa-2fc7-4dbb-6be9-beb823318303

      • session.json

.gen/sessions/0d0d0c2f-6bb9-405f-6a41-d4fe9acf3dd2/session.json

{
    "Name": "world"
}

Each subdirectory (domain) takes the id of a session and it contains the state in a session.json file (key), thus, there are as many subdirectories as there are sessions.