Astro.session

[ascorbic]

Summary

I am proposing a first class Astro.session primitive, with pluggable storage backends (possibly based on unstorage). Inspired by PHP sessions and Rails sessions, this will allow on-demand rendered pages and API endpoints to use a new Astro.session object to access arbitrary data, scoped to that browser session. A session ID cookie is used to associate the browser with the session, but the actual data is stored on the backend.

Background and motivation

HTTP is a stateless protocol, so sharing data between requests is a problem that most server-rendered web apps need to solve. The standard way is using cookies, but these have limitations. Firstly, they are limited to 4kB in size, so can't be used for anything complex. The full data also needs to be sent along with every request and response, increasing their size. Finally, even when encrypted they can be vulnerable to replay attacks. We have encountered the limitations of cookie storage when building Astro Actions, where we need response data to persist between page redirects. It is easy to reach the 4kB limit in these cases.

For this reasons, most non-trivial apps need to implement some kind of server-side session handling. In most cases these work by storing a random session id in a cookie, and using that to retrieve the full session data on the server. Monolithic frameworks such as Rails and Laravel normally implement sessions at the framework or server level, and PHP has built-in session handling which heavily influenced this proposal. However it isn't a common primitive for modern JS frameworks, in part due to the fact that these need to work in serverless environments, so simple default backends such as filesystem storage cannot be relied upon. We propose addressing this by allowing adapters to provide default implementations, relying on the primitives that they have available.

Goals

• Simple key/value API, similar to Astro.cookies (Astro.session.get(), Astro.session.set())
• Additional control over the session via methods such as Astro.session.regenerateId() and Astro.session.destroy()
• Adapters can provide default backends and others are pluggable via a new session config object.
• Other settings such as cookie name, session expiry etc are also optionally configurable
• Sessions are lazy-loaded and auto-generated when first accessed. Session ID cookie is get and set automatically

Non-goals

• User management, auth etc. This is just raw sessions, but they may be useful if someone is implementing auth

Example

---
let cart = Astro.session.get('cart')
if (!cart) {
	cart = createNewCart()
	Astro.session.set('cart', cart)
}
---

<div>{cart.items.length} items</div>

// astro.config.ts
import { defineConfig } from "astro/config"
import planetscaleDriver from "unstorage/drivers/planetscale";

export default defineConfig({
  output: "server",
  adapter: nodejs({
    mode: 'standalone',
  }),
  session: {
    storage: planetscaleDriver({
      url: import.meta.env.PLANETSCALE_URL
    })
  }
})
  

References

• PHP Sessions
• Laravel sessions
• How Rails sessions work
• Securing Rails sessions
• A previous proposal on Astro sessions, though this was more focussed on sharing data between server and client.

[bholmesdev]

Love everything proposed here! I agree that sessions should be pluggable. I'd personally reach for Upstash + a serverless deploy platform to implement sessions.

Should it be possible for adapters to inject a default session handler that can be overridden in the config? Or should it be an explicit session.storage config as shown in the Planetscale example? I could see the Node adapter applying a default session storage.

[ascorbic]

Yes, absolutely. I would imagine that the Node adapter would default to filesystem storage, Netlify to Netlify Blobs, Cloudflare to Workers KV, Deno to Deno KV. Sadly Vercel KV RIP, but an easy Upstash KV driver would do the trick there.

[Princesseuh]

Looks great, would love to see this as a primitive in Astro. We're bringing back PHP.

[pilcrowonpaper]

I might be missing something, but this seems pretty trivial to implement in userland with Astro.locals and could be packaged as an Astro integration/middleware.

[pilcrowonpaper]

@bholmesdev Maybe it's just me, but it'd be kinda weird if a feature built into Astro didn't work in some environment by default. I definitely understand how sessions could be useful tho

[ematipico]

@bholmesdev Maybe it's just me, but it'd be kinda weird if a feature built into Astro didn't work in some environment by default. I definitely understand how sessions could be useful tho

It's definitely weird, but it's something we already do. For example, edge middleware isn't supported by Cloudflare nowadays

[pilcrowonpaper]

@ematipico I was under the impression that edge middleware is a feature of the Vercel adapter and not Astro

[ascorbic]

No, it's a core feature that relies on support in adapters. Netlify and Vercel are the ones that do, I think.

[ematipico]

Yes, it's a feature provided by adapters, opt-in. Astro provides the glue for that. If the infrastructure (the hosting provider), doesn't support it, adapters shouldn't opt-in

[nielsodgaard]

Cool! Would this also be useable for sharing data between server and client (JS frameworks)?

[ascorbic]

No, that's not in scope for this. I do link to another proposal that does cover that, but I wanted to keep the scope narrow for this.

[florian-lefebvre]

FYI this is possible already using an integration: https://inox-tools.fryuni.dev/request-state

[ascorbic]

This has been accepted to stage 2. Continue any discussion here: #1050