firestore

README

firestore

A Google Cloud Firestore based session store for SCS.

Setup

You should follow the instructions to install and open a database, and pass the database to firestore.New() to establish the session store.

The default collection is "Sessions". If you want to change that, store a custom CollectionRef in scsfs.Sessions.

Example

package main

import (
	"context"
	"io"
	"log"
	"net/http"
	"os"

	"cloud.google.com/go/firestore"
	scsfs "github.com/golangcollege/scs/firestore"
	"github.com/golangcollege/scs/v2"
)

var sessionManager *scs.SessionManager

func main() {
	// Establish connection to Google Cloud Firestore.
	db, err := firestore.NewClient(context.Background(), os.Getenv("GOOGLE_CLOUD_PROJECT"))
	if err != nil {
		log.Fatal(err)
	}

	// Initialize a new session manager and configure it to use firestore as the session store.
	sessionManager = scs.New()
	sessionManager.Store = scsfs.New(db)

	mux := http.NewServeMux()
	mux.HandleFunc("/put", putHandler)
	mux.HandleFunc("/get", getHandler)

	http.ListenAndServe(":4000", sessionManager.LoadAndSave(mux))
}

func putHandler(w http.ResponseWriter, r *http.Request) {
	sessionManager.Put(r.Context(), "message", "Hello from a session!")
}

func getHandler(w http.ResponseWriter, r *http.Request) {
	msg := sessionManager.GetString(r.Context(), "message")
	io.WriteString(w, msg)
}

The sample can be run by setting the environment variable GOOGLE_CLOUD_PROJECT, which should be proper project id. If you have the local firestore emulator (part of the Google Cloud SDK) installed you can start a local emulator and run the example like this:

Start the emulator first:

gcloud beta emulators firestore start --host-port=localhost:8041

Then test the example program:

FIRESTORE_EMULATOR_HOST=localhost:8041 GOOGLE_CLOUD_PROJECT=test go run .

Documentation

Index

• type FireStore
  • func New(client *firestore.Client) *FireStore
  • func NewWithCleanupInterval(client *firestore.Client, cleanupInterval time.Duration) *FireStore
  • func (m *FireStore) AllCtx(ctx context.Context) (map[string][]byte, error)
  • func (m *FireStore) Commit(token string, b []byte, expiry time.Time) error
  • func (m *FireStore) CommitCtx(ctx context.Context, token string, b []byte, expiry time.Time) error
  • func (m *FireStore) Delete(token string) error
  • func (m *FireStore) DeleteCtx(ctx context.Context, token string) error
  • func (m *FireStore) Find(token string) ([]byte, bool, error)
  • func (m *FireStore) FindCtx(ctx context.Context, token string) ([]byte, bool, error)
  • func (m *FireStore) StopCleanup()

Types

type FireStore

type FireStore struct {
	*firestore.Client
	Sessions *firestore.CollectionRef
	// contains filtered or unexported fields
}

FireStore represents the session store.

func New

func New(client *firestore.Client) *FireStore

New returns a new FireStore instance, with a background cleanup goroutine that runs every 5 minutes to remove expired session data.

func NewWithCleanupInterval

func NewWithCleanupInterval(client *firestore.Client, cleanupInterval time.Duration) *FireStore

NewWithCleanupInterval returns a new FireStore instance. The cleanupInterval parameter controls how frequently expired session data is removed by the background cleanup goroutine. Setting it to 0 prevents the cleanup goroutine from running (i.e. expired sessions will not be removed).

func (*FireStore) AllCtx

func (m *FireStore) AllCtx(ctx context.Context) (map[string][]byte, error)

AllCtx returns a map containing the token and data for all active (i.e. not expired) sessions in the firestore instance.

func (*FireStore) Commit

func (m *FireStore) Commit(token string, b []byte, expiry time.Time) error

func (*FireStore) CommitCtx

func (m *FireStore) CommitCtx(ctx context.Context, token string, b []byte, expiry time.Time) error

CommitCtx adds a session token and data to the FireStore instance with the given expiry time. If the session token already exists, then the data and expiry time are updated.

func (*FireStore) Delete

func (m *FireStore) Delete(token string) error

func (*FireStore) DeleteCtx

func (m *FireStore) DeleteCtx(ctx context.Context, token string) error

DeleteCtx removes a session token and corresponding data from the FireStore instance.

func (*FireStore) Find

func (m *FireStore) Find(token string) ([]byte, bool, error)

func (*FireStore) FindCtx

func (m *FireStore) FindCtx(ctx context.Context, token string) ([]byte, bool, error)

FindCtx returns the data for a given session token from the FireStore instance. If the session token is not found or is expired, the returned exists flag will be set to false.

func (*FireStore) StopCleanup

func (m *FireStore) StopCleanup()

StopCleanup terminates the background cleanup goroutine for the FireStore instance. It's rare to terminate this; generally FireStore instances and their cleanup goroutines are intended to be long-lived and run for the lifetime of your application.

There may be occasions though when your use of the FireStore is transient. An example is creating a new FireStore instance in a test function. In this scenario, the cleanup goroutine (which will run forever) will prevent the MySQLStore object from being garbage collected even after the test function has finished. You can prevent this by manually calling StopCleanup.