RFC: HTTP Session Support (draft)

[matthewmueller]

HTTP Sessions

HTTP is a stateless protocol on it's own – you can't tell who made which request. Sessions are built on top of HTTP to map requests to devices. This mapping helps you provide Authentication and Authorization.

Enabling HTTP Session Support

You can add sessions to your application by defining a Session struct inside your application's session package:

$YOUR_APP
 └ session
   └ session.go

And inside session/session.go:

package session

// Session data
type Session struct {
  ID *string // Application-specific ID
}

By defining a Session in session/session.go, you've enabled session management. The session cookie will now be sent in the response from all your controller/ routes, regardless of whether your actions use the session.

With the session now defined, the Session data will now be persistent for each device across requests using an encrypted HTTP cookie. Whenever you update the fields inside the Session struct, you'll see the updated data in subsequent requests.

(TODO: Screenshot of the Browser Storage tab)

You can now use this session in your controllers:

package controller

import (
  "your.app.com/session"
)

type Controller struct {
  Session *session.Session
}

func (c *Controller) Index() {}

Scaffolding Sessions

(TODO: there should also be a bud new session something)

Extending Sessions

Within the session package, you can extend the session by building types that depend on the Session. Types like User below. These types can be initialized using functions that support automatic Dependency Injection.

type Session struct {
  ID *int
}

func LoadUser(db *sql.Database, session *Session) (*User, error) {
  if session.ID == nil {
    return nil, nil
  }
  // hypothetical database call
  return db.FindUserByID(*session.ID)
}

type User struct {
  *db.User // hypothetical struct containing user table data
}

You can then depend on the session.User from your controllers:

package controller

import (
  "your.app.com/session"
)

type Controller struct {
  User *session.User
}

func (c *Controller) Index() {}

This helps cut down on the boilerplate. Instead of loading dependent data in each controller, you can define that logic once in the session package and share those types across your controllers.

Authentication

Now that we've defined a user session, we can use that session in a controller. To demonstrate this, let's implement login and logout actions. To do this, I'll create a session controller, but the name of the controller doesn't matter:

myapp
├── controller
│   └── session
│       └── controller.go
└── session
    └── user.go

Here's what the session controller might look like:

package session

import (
  "your.app.com/session"
)

type Controller struct {
	Session *session.Session
}

// Login by creating a session
func (c *Controller) Create(email, password string) error {
	// Authenticate the user (using SQL, an ORM, etc.)
	user, err := authenticateUser(email, password)
	if err != nil {
		return err
	}
	// Store the user ID in the session
	c.Session.ID = &user.ID
	return nil
}

// Logout by deleting the session
func (c *Controller) Delete() {
	c.Session.ID = nil
}

Visitors

Sessions are broader than signup, login and logout. Sessions simply tie requests to a device. A user doesn't need to be logged in for sessions to be useful.

To see this in action, let's add a property that applies to everyone, even visitors:

// Session data
type Session struct {
  LastVisited *int
}

where `LastVisited` defines the number of seconds since the last visit, `nil` means they haven't visited before.

```go
package posts

import (
	"fmt"
	"time"
)

type Controller struct {
	User *session.User
}

func (c *Controller) Show(id int) (*Post, error) {
	now := time.Now().Unix()
	if c.User.LastVisited == nil {
		fmt.Println("first time visitor!")
		c.User.LastVisited = now
	} else {
		fmt.Println("last visited", now.Sub(c.User.LastVisited))
		c.User.LastVisited = now
	}
}

(TODO: cleanup this example now that we've explained Extending the Session above.)

In the code above, we first check if the request is from a first-time visitor, otherwise we take the difference between now and the last time they visited the website.

Authorization

While authentication helps you map a request to a user, authorization defines what a user is allowed to do. For example, for a blog, every reader can read a blog post, but only editors can edit a blog post.

• Authentication: is this request a Reader or an Editor?
• Authorization: Readers can only read, Editors can read and write.

We can implement authorization easily by expanding the Session struct in the session package:

package session

// User session
type Session struct {
	ID      *string
	CanEdit bool
}

All fields are persisted across requests for a given device. So if you set the CanEdit field on one request, you'll see that field on the set on the next request.

TODO: show authentication example setting CanEdit during login

With CanEdit in place, now when someone logs in, we can use the CanEdit boolean to decide whether or not they can edit or update the blog post:

package posts

import "errors"

type Controller struct {
	User *session.User
}

func (c *Controller) Edit(id int, post string) (*Post, error) {
	if !c.User.CanEdit {
		return nil, errors.New("You're not allowed to edit blog posts")
	}
	return nil, nil
}

func (c *Controller) Update(id int, post string) error {
	if !c.User.CanEdit {
		return nil, errors.New("You're not allowed to update blog posts")
	}
}

Open Questions

• Anything confusing or any use cases I'm missing?
• Should this be top-level or within another package like web/session/session.go?
• Is the HTTP response cookie session storage provider good enough or do we need hooks to bring your own session storage provider?
• Should the framework provide data like LastVisited by default? See Laravel's docs below to see what I mean by the framework bringing some of its own session fields. Generic support will make this so much easier now to have a custom payload data within a framework-provided session wrapper.

Resources

• Laravel's HTTP session support was a big inspiration here: https://laravel.com/docs/9.x/session

[austincollinpena]

Should the framework provide data like LastVisited by default? See Laravel's docs below to see what I mean by the framework bringing some of its own session fields. Generic support will make this so much easier now to have a custom payload data within a framework-provided session wrapper.

I personally don't think so. I'd rather keep the "bones" there and not do anything opinionated like like load user into the Session by default like Django does. Some routes don't need any data, so they shouldn't be given data by default.

[syke99]

Should this be top-level or within another package like web/session/session.go?

I would put it in its own package to keep functionality separate, but I would keep it as close to top level as possible to prevent a user from creating a circular dependency cycle as much as possible. With sessions being important in large scale web apps, I could see users wanting to pass that struct around, and if they're not careful, creating such a dependency cycle

[jnehlmeier]

Is the HTTP response cookie session storage provider good enough or do we need hooks to bring your own session storage provider?

I am pretty sure you need custom session storage providers.

• Cookies have size limits, see: https://chromestatus.com/feature/4946713618939904 (browser implementations might differ)
• You never know what people want to put into a session. Is only string allowed so you don't have to serialize the data? Seems limiting. There are cases you want to assign complex data to a session.
• Encryption/decryption on every request is some overhead

There should be a solution for the common choices:

• store session data on the client (at least signed and optionally encrypted in case of sensitive server data in a session)
• store session data on the server
• store session data in a database or other third party stores (e.g. Hazelcast, Redis, ...) to support session replication across server nodes

Additional notes:

• Sessions should be accessible outside of requests as long as you know the session id. This is useful if you opt-in for server side session storage and you have background tasks that want to update a session.

[matthewmueller]

Thanks for your feedback Jens! Need to think more about what you wrote, but right now I think I agree with all your points.

I also appreciate the additional note about accessing sessions out of the request-response lifecycle. I hadn't considered that, but it makes a ton of sense!

[austincollinpena]

I like https://github.com/gorilla/securecookie a lot for cookie management

[matthewmueller]

Heads up: I'd like to revisit this a bit now that generics are becoming more ubiquitous. I could see the custom data being wrapped by types offered by Bud.

func Signout(session *bud.Session[session.Data]) {
  session.Destroy()
}

In $APP/session/session.go

type Session struct {
  // Custom user session data
}

Then in $BUD/session.go:

type Session[Data] struct {
  Data Data
  // private state...
  id string
}

func (s *Session) Destroy() {
  // ...
}