feat(cloudflare): add KV session storage support

[ascorbic]

Changes

Adds support for automatically-provisioning session storage for Cloudflare KV

Automatically configures Cloudflare KV storage when experimental sessions are enabled

If the experimental.session flag is enabled when using the Cloudflare adapter, Astro will automatically configure the session storage using the Cloudflare KV driver. You can still manually configure the session storage if you need to use a different driver or want to customize the session storage configuration. If you want to use sessions, you will need to create the KV namespace and declare it in your wrangler config. You can do this using the Wrangler CLI:

npx wrangler kv namespace create SESSION

This will log the id of the created namespace. You can then add it to your wrangler.json/wrangler.toml file like this:

// wrangler.json
{
  "kv_namespaces": [
    {
      "binding": "SESSION",
      "id": "<your kv namespace id here>"
    }
  ]
}

By default it uses the binding name SESSION, but if you want to use a different binding name you can do so by passing the sessionKVBindingName option to the adapter. For example:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
  output: 'server',
  site: `http://example.com`,
  adapter: cloudflare({
    platformProxy: {
      enabled: true,
    },
    sessionKVBindingName: 'MY_SESSION',
  }),
  experimental: {
    session: true,
  }
});

Testing

Adds fixture and test suite. To try it on your own site, use the preview release of @astrojs/cloudflare

Docs

Needs updated docs

[changeset-bot]

🦋 Changeset detected

Latest commit: fd17d36

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

astro

npm i https://pkg.pr.new/astro@13514

@astrojs/cloudflare

npm i https://pkg.pr.new/@astrojs/cloudflare@13514

@astrojs/netlify

npm i https://pkg.pr.new/@astrojs/netlify@13514

@astrojs/node

npm i https://pkg.pr.new/@astrojs/node@13514

@astrojs/vercel

npm i https://pkg.pr.new/@astrojs/vercel@13514

commit: 20237b8

[ematipico]

Awesome 🔥

[ematipico]

Can we comment on the usage and the why of these two globals?

[ematipico]

Should we tell users what will happen if they forget to add this namespace? Since we can't catch the error at runtime, the least we can do tell users what will happen if they miss this step

[ascorbic]

I've added an explicit message saying what the error would be

[ematipico]

Whether this is a nitpick or not, I foresee a use case where users might want to override this because they don't want to leak information relative to their framework. However, I think it's fine to keep it like this for now, and re-iterate if users need to overrde it

[ascorbic]

They can override the actual binding name: this is just the name of the variable we use to pass it to unstorage.

[ascorbic]

I've changed it to use the same name as the binding, because otherwise the error message from unstorage would be confusing.

[ascorbic]

I've added this to the 5.6 milestone just for the purposes of blogs, as it's an experimental feature