feat(sessions): drivers (#15006)

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

Author: florian-lefebvre

.changeset/bright-parrots-hear.md

@@ -0,0 +1,5 @@
+---
+'astro': major
+---
+
+Removes session `test` driver - ([v6 upgrade guidance](https://v6.docs.astro.build/en/guides/upgrade-to/v6/#removed-session-test-driver))

.changeset/clever-clubs-listen.md

@@ -0,0 +1,5 @@
+---
+'astro': major
+---
+
+Deprecates session driver string signature - ([v6 upgrade guidance](https://v6.docs.astro.build/en/guides/upgrade-to/v6/#deprecated-session-driver-string-signature))

.changeset/solid-fans-jam.md

@@ -0,0 +1,29 @@
+---
+'@astrojs/cloudflare': minor
+'@astrojs/netlify': minor
+'@astrojs/node': minor
+'astro': minor
+---
+
+Adds new session driver object shape
+
+For greater flexibility and improved consistency with other Astro code, session drivers are now specified as an object:
+
+```diff
+-import { defineConfig } from 'astro/config'
++import { defineConfig, sessionDrivers } from 'astro/config'
+
+export default defineConfig({
+  session: {
+-    driver: 'redis',
+-    options: {
+-      url: process.env.REDIS_URL
+-    },
++    driver: sessionDrivers.redis({
++      url: process.env.REDIS_URL
++    }),
+  }
+})
+```
+
+Specifying the session driver as a string has been deprecated, but will continue to work until this feature is removed completely in a future major version. The object shape is the current recommended and documented way to configure a session driver.

packages/astro/src/config/entrypoint.ts

@@ -10,6 +10,7 @@ export { mergeConfig } from '../core/config/merge.js';
 export { validateConfig } from '../core/config/validate.js';
 export { envField } from '../env/config.js';
 export { defineConfig, getViteConfig } from './index.js';
+export { sessionDrivers } from '../core/session/drivers.js';
 
 /**
  * Return the configuration needed to use the Sharp-based image service

packages/astro/src/config/index.ts

@@ -1,19 +1,15 @@
 import type { UserConfig as ViteUserConfig, UserConfigFn as ViteUserConfigFn } from 'vite';
 import { createRoutesList } from '../core/routing/index.js';
-import type {
-	AstroInlineConfig,
-	AstroUserConfig,
-	Locales,
-	SessionDriverName,
-} from '../types/public/config.js';
+import type { AstroInlineConfig, AstroUserConfig, Locales } from '../types/public/config.js';
+import type { SessionDriverConfig, SessionDriverName } from '../core/session/types.js';
 
 /**
  * See the full Astro Configuration API Documentation
  * https://astro.build/config
  */
 export function defineConfig<
 	const TLocales extends Locales = never,
-	const TDriver extends SessionDriverName = never,
+	const TDriver extends SessionDriverName | SessionDriverConfig = never,
 >(config: AstroUserConfig<TLocales, TDriver>) {
 	return config;
 }

packages/astro/src/core/app/base.ts

@@ -27,7 +27,7 @@ import { type CreateRenderContext, RenderContext } from '../render-context.js';
 import { redirectTemplate } from '../routing/3xx.js';
 import { ensure404Route } from '../routing/astro-designed-error-pages.js';
 import { matchRoute } from '../routing/match.js';
-import { type AstroSession, PERSIST_SYMBOL } from '../session.js';
+import { type AstroSession, PERSIST_SYMBOL } from '../session/runtime.js';
 import type { AppPipeline } from './pipeline.js';
 import type { SSRManifest } from './types.js';
 

packages/astro/src/core/app/types.ts

@@ -6,7 +6,6 @@ import type {
 	CspAlgorithm,
 	Locales,
 	RemotePattern,
-	ResolvedSessionConfig,
 } from '../../types/public/config.js';
 import type {
 	RouteData,
@@ -17,8 +16,8 @@ import type {
 import type { SinglePageBuiltModule } from '../build/types.js';
 import type { CspDirective } from '../csp/config.js';
 import type { LoggerLevel } from '../logger/core.js';
-import type { SessionDriver } from '../session.js';
 import type { RoutingStrategies } from './common.js';
+import type { BaseSessionConfig, SessionDriverFactory } from '../session/types.js';
 
 type ComponentPath = string;
 
@@ -96,10 +95,10 @@ export type SSRManifest = {
 	i18n: SSRManifestI18n | undefined;
 	middleware?: () => Promise<AstroMiddlewareInstance> | AstroMiddlewareInstance;
 	actions?: () => Promise<SSRActions> | SSRActions;
-	sessionDriver?: () => Promise<{ default: SessionDriver | null }>;
+	sessionDriver?: () => Promise<{ default: SessionDriverFactory | null }>;
 	checkOrigin: boolean;
 	allowedDomains?: Partial<RemotePattern>[];
-	sessionConfig?: ResolvedSessionConfig<any>;
+	sessionConfig?: SSRManifestSession;
 	cacheDir: URL;
 	srcDir: URL;
 	outDir: URL;
@@ -152,6 +151,11 @@ export type SSRManifestCSP = {
 	directives: CspDirective[];
 };
 
+export interface SSRManifestSession extends BaseSessionConfig {
+	driver: string;
+	options?: Record<string, any> | undefined;
+}
+
 /** Public type exposed through the `astro:build:ssr` integration hook */
 export type SerializedSSRManifest = Omit<
 	SSRManifest,

packages/astro/src/core/base-pipeline.ts

@@ -23,7 +23,7 @@ import { sequence } from './middleware/sequence.js';
 import { RedirectSinglePageBuiltModule } from './redirects/index.js';
 import { RouteCache } from './render/route-cache.js';
 import { createDefaultRoutes } from './routing/default.js';
-import type { SessionDriver } from './session.js';
+import type { SessionDriverFactory } from './session/types.js';
 
 /**
  * The `Pipeline` represents the static parts of rendering that do not change between requests.
@@ -35,7 +35,7 @@ export abstract class Pipeline {
 	readonly internalMiddleware: MiddlewareHandler[];
 	resolvedMiddleware: MiddlewareHandler | undefined = undefined;
 	resolvedActions: SSRActions | undefined = undefined;
-	resolvedSessionDriver: SessionDriver | null | undefined = undefined;
+	resolvedSessionDriver: SessionDriverFactory | null | undefined = undefined;
 
 	constructor(
 		readonly logger: Logger,
@@ -143,7 +143,7 @@ export abstract class Pipeline {
 		return NOOP_ACTIONS_MOD;
 	}
 
-	async getSessionDriver(): Promise<SessionDriver | null> {
+	async getSessionDriver(): Promise<SessionDriverFactory | null> {
 		// Return cached value if already resolved (including null)
 		if (this.resolvedSessionDriver !== undefined) {
 			return this.resolvedSessionDriver;

packages/astro/src/core/build/plugins/plugin-manifest.ts

@@ -35,6 +35,7 @@ import type { BuildInternals } from '../internal.js';
 import { cssOrder, mergeInlineCss } from '../runtime.js';
 import type { StaticBuildOptions } from '../types.js';
 import { makePageDataKey } from './util.js';
+import { sessionConfigToManifest } from '../../session/utils.js';
 
 /**
  * Unified manifest system architecture:
@@ -369,7 +370,7 @@ async function buildManifest(
 			(settings.config.security?.checkOrigin && settings.buildOutput === 'server') ?? false,
 		allowedDomains: settings.config.security?.allowedDomains,
 		key: encodedKey,
-		sessionConfig: settings.config.session,
+		sessionConfig: sessionConfigToManifest(settings.config.session),
 		csp,
 		devToolbar: {
 			enabled: false,

packages/astro/src/core/config/schemas/base.ts

@@ -13,6 +13,7 @@ import { localFontFamilySchema, remoteFontFamilySchema } from '../../../assets/f
 import { EnvSchema } from '../../../env/schema.js';
 import type { AstroUserConfig, ViteUserConfig } from '../../../types/public/config.js';
 import { allowedDirectivesSchema, cspAlgorithmSchema, cspHashSchema } from '../../csp/config.js';
+import { SessionSchema } from '../../session/config.js';
 
 // The below types are required boilerplate to workaround a Zod issue since v3.21.2. Since that version,
 // Zod's compiled TypeScript would "simplify" certain values to their base representation, causing references
@@ -95,7 +96,6 @@ export const ASTRO_CONFIG_DEFAULTS = {
 		schema: {},
 		validateSecrets: false,
 	},
-	session: undefined,
 	prerenderConflictBehavior: 'warn',
 	experimental: {
 		clientPrerender: false,
@@ -466,30 +466,7 @@ export const AstroConfigSchema = z.object({
 		.strict()
 		.optional()
 		.default(ASTRO_CONFIG_DEFAULTS.env),
-	session: z
-		.object({
-			driver: z.string().optional(),
-			options: z.record(z.string(), z.any()).optional(),
-			cookie: z
-				.object({
-					name: z.string().optional(),
-					domain: z.string().optional(),
-					path: z.string().optional(),
-					maxAge: z.number().optional(),
-					sameSite: z.union([z.enum(['strict', 'lax', 'none']), z.boolean()]).optional(),
-					secure: z.boolean().optional(),
-				})
-				.or(z.string())
-				.transform((val) => {
-					if (typeof val === 'string') {
-						return { name: val };
-					}
-					return val;
-				})
-				.optional(),
-			ttl: z.number().optional(),
-		})
-		.optional(),
+	session: SessionSchema.optional(),
 	prerenderConflictBehavior: z
 		.enum(['error', 'warn', 'ignore'])
 		.optional()