Some or all of the information on this page might not apply to Cloud de Confiance by S3NS. See Differences from Google Cloud for more details.

Handling sessions with Firestore

This tutorial shows how to handle sessions on Cloud Run.

Many apps need session handling for authentication and user preferences. The Gorilla Web Toolkit sessions package comes with a file system based implementation to perform this function. However, this implementation is unsuitable for an app that can be served from multiple instances, because the session that is recorded in one instance might differ from other instances. The gorilla/sessions package also comes with a cookie-based implementation. But, this implementation requires encrypting cookies and storing the entire session on the client, rather than just a session ID, which may be too large for some apps.

Setting up the project

In your terminal window, clone the sample app repository to your local machine:
```
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
```
Change to the directory that contains the sample code:
```
cd golang-samples/getting-started/sessions
```

Understanding the web app

This app displays greetings in different languages for every user. Returning users are always greeted in the same language.

Multiple app windows displaying a greeting in different languages.

Before the app can store preferences for a user, you need a way to store information about the current user in a session. This sample app uses Firestore to store session data.

The app starts by importing dependencies, defining an app type to hold a sessions.Store and an HTML template, and defining the list of greetings.

import (
	"context"
	"html/template"
	"log"
	"math/rand"
	"net/http"
	"os"

	"cloud.google.com/go/firestore"
)

// app stores a sessions.Store. Create a new app with newApp.
type app struct {
	tmpl         *template.Template
	collectionID string
	projectID    string
}

// session stores the client's session information.
// This type is also used for executing the template.
type session struct {
	Greetings string `json:"greeting"`
	Views     int    `json:"views"`
}

// greetings are the random greetings that will be assigned to sessions.
var greetings = []string{
	"Hello World",
	"Hallo Welt",
	"Ciao Mondo",
	"Salut le Monde",
	"Hola Mundo",
}

Next, the app defines a main function, which creates a new app instance, registers the index handler, and starts the HTTP server. The newApp function creates the app instance by setting projectID and collectionID values and parses the HTML template.

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}

	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	if projectID == "" {
		log.Fatal("GOOGLE_CLOUD_PROJECT must be set")
	}

	// collectionID is a non-empty identifier for this app, it is used as the Firestore
	// collection name that stores the sessions.
	//
	// Set it to something more descriptive for your app.
	collectionID := "hello-views"

	a, err := newApp(projectID, collectionID)
	if err != nil {
		log.Fatalf("newApp: %v", err)
	}

	http.HandleFunc("/", a.index)

	log.Printf("Listening on port %s", port)
	if err := http.ListenAndServe(":"+port, nil); err != nil {
		log.Fatal(err)
	}
}

// newApp creates a new app.
func newApp(projectID, collectionID string) (app, error) {
	tmpl, err := template.New("Index").Parse(`<body>{{.Views}} {{if eq .Views 1}}view{{else}}views{{end}} for "{{.Greetings}}"</body>`)
	if err != nil {
		log.Fatalf("template.New: %v", err)
	}

	return app{
		tmpl:         tmpl,
		collectionID: collectionID,
		projectID:    projectID,
	}, nil
}

The index handler gets the user's session, creating one if needed. New sessions are assigned a random language and a view count of 0. Then, the view count is increased by one, the session is saved, and the HTML template writes the response.


// index uses sessions to assign users a random greeting and keep track of
// views.
func (a *app) index(w http.ResponseWriter, r *http.Request) {
	// Allows requests only for the root path ("/") to prevent duplicate calls.
	if r.RequestURI != "/" {
		http.NotFound(w, r)
		return
	}

	var session session
	var doc *firestore.DocumentRef

	isNewSession := false

	ctx := context.Background()

	client, err := firestore.NewClient(ctx, a.projectID)
	if err != nil {
		log.Fatalf("firestore.NewClient: %v", err)
	}
	defer client.Close()

	// cookieName is a non-empty identifier for this app, it is used as the key name
	// that contains the session's id value.
	//
	// Set it to something more descriptive for your app.
	cookieName := "session_id"

	// If err is different to nil, it means the cookie has not been set, so it will be created.
	cookie, err := r.Cookie(cookieName)
	if err != nil {
		// isNewSession flag is set to true
		isNewSession = true
	}

	// If isNewSession flag is true, the session will be created
	if isNewSession {
		// Get unique id for new document
		doc = client.Collection(a.collectionID).NewDoc()

		session.Greetings = greetings[rand.Intn(len(greetings))]
		session.Views = 1

		// Cookie is set
		cookie = &http.Cookie{
			Name:  cookieName,
			Value: doc.ID,
		}
		http.SetCookie(w, cookie)
	} else {
		// The session exists

		// Retrieve document from collection by ID
		docSnapshot, err := client.Collection(a.collectionID).Doc(cookie.Value).Get(ctx)
		if err != nil {
			log.Printf("doc.Get error: %v", err)
			http.Error(w, "Error getting session", http.StatusInternalServerError)
			return
		}

		// Unmarshal documents's content to local type
		err = docSnapshot.DataTo(&session)
		if err != nil {
			log.Printf("doc.DataTo error: %v", err)
			http.Error(w, "Error parsing session", http.StatusInternalServerError)
			return
		}

		doc = docSnapshot.Ref

		// Add 1 to current views value
		session.Views++
	}

	// The document is created/updated
	_, err = doc.Set(ctx, session)
	if err != nil {
		log.Printf("doc.Set error: %v", err)
		http.Error(w, "Error creating session", http.StatusInternalServerError)
		return
	}

	if err := a.tmpl.Execute(w, session); err != nil {
		log.Printf("Execute: %v", err)
	}
}

The following diagram illustrates how Firestore handles sessions for the Cloud Run app.

Diagram of architecture: user, Cloud Run, Firestore.

Deleting sessions

You can delete session data in the Cloud de Confiance console or implement an automated deletion strategy. If you use storage solutions for sessions such as Memcache or Redis, expired sessions are automatically deleted.

Running locally

In your terminal window, build the sessions binary:
```
go build
```
Start the HTTP server:
```
./sessions
```
View the app in your web browser:

Cloud Shell

In the Cloud Shell toolbar, click Web preview and select Preview on port 8080.

Local machine

In your browser, go to http://localhost:8080

You see one of five greetings: “Hello World”, “Hallo Welt”, "Hola mundo”, “Salut le Monde”, or “Ciao Mondo.” The language changes if you open the page in a different browser or in incognito mode. You can see and edit the session data in the Cloud de Confiance console.
To stop the HTTP server, in your terminal window, press Control+C.

Deploying and running on Cloud Run

You can use the Cloud Run to build and deploy an app that runs reliably under heavy load and with large amounts of data.

Deploy the app on Cloud Run:

    gcloud run deploy firestore-tutorial-go 

    --source . --allow-unauthenticated --port=8080 

    --set-env-vars=GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

Visit the URL returned by this command to see how session data persists between page loads.

The greeting is now delivered by a web server running on an Cloud Run instance.

Debugging the app

If you cannot connect to your Cloud Run app, check the following:

Check that the gcloud deploy commands successfully completed and didn't output any errors. If there were errors (for example, message=Build failed), fix them, and try deploying the Cloud Run app again.
In the Cloud de Confiance console, go to the Logs Explorer page.

Go to Logs Explorer page
1. In the Recently selected resources drop-down list, click Cloud Run Application, and then click All module_id. You see a list of requests from when you visited your app. If you don't see a list of requests, confirm you selected All module_id from the drop-down list. If you see error messages printed to the Cloud de Confiance console, check that your app's code matches the code in the section about writing the web app.
2. Make sure that the Firestore API is enabled.