Allow passing platform context from adapters

.changeset/cyan-numbers-change.md

@@ -0,0 +1,6 @@
+---
+'@sveltejs/adapter-cloudflare': patch
+'@sveltejs/adapter-node': patch
+---
+
+Pass `platform` object to SvelteKit

.changeset/many-mayflies-clap.md

@@ -0,0 +1,6 @@
+---
+'create-svelte': patch
+'@sveltejs/kit': patch
+---
+
+Allow adapters to pass in `platform` object

documentation/docs/01-routing.md

@@ -51,11 +51,12 @@ Endpoints are modules written in `.js` (or `.ts`) files that export functions co
 // Declaration types for Endpoints
 // * declarations that are not exported are for internal use
 
-export interface RequestEvent<Locals = Record<string, any>> {
+export interface RequestEvent<Locals = Record<string, any>, Platform = Record<string, any>> {
 	request: Request;
 	url: URL;
 	params: Record<string, string>;
 	locals: Locals;
+	platform: Platform;
 }
 
 type Body = JSONString | Uint8Array | ReadableStream | stream.Readable;
@@ -69,8 +70,13 @@ type MaybePromise<T> = T | Promise<T>;
 interface Fallthrough {
 	fallthrough: true;
 }
-export interface RequestHandler<Locals = Record<string, any>, Output extends Body = Body> {
-	(event: RequestEvent<Locals>): MaybePromise<
+
+export interface RequestHandler<
+	Locals = Record<string, any>,
+	Platform = Record<string, any>,
+	Output extends Body = Body
+> {
+	(event: RequestEvent<Locals, Platform>): MaybePromise<
 		Either<Response | EndpointOutput<Output>, Fallthrough>
 	>;
 }
@@ -194,6 +200,10 @@ A route can have multiple dynamic parameters, for example `src/routes/[category]
 
 > `src/routes/a/[...rest]/z.svelte` will match `/a/z` as well as `/a/b/z` and `/a/b/c/z` and so on. Make sure you check that the value of the rest parameter is valid.
 
+#### Platform object
+
+Some adapters may pass in some extra context when calling your application. They do this by setting the `platform` object, that can be accessed in both route handlers and hooks ([detailed later](#hooks)). It is up to the adapter to decide what is passed in.
+
 #### Fallthrough routes
 
 Finally, if you have multiple routes that match a given path, SvelteKit will try each of them until one responds. For example if you have these routes...

documentation/docs/04-hooks.md

@@ -22,21 +22,22 @@ If unimplemented, defaults to `({ event, resolve }) => resolve(event)`.
 // everything else must be a type of string
 type ResponseHeaders = Record<string, string | string[]>;
 
-export interface RequestEvent<Locals = Record<string, any>> {
+export interface RequestEvent<Locals = Record<string, any>, Platform = Record<string, any>> {
 	request: Request;
 	url: URL;
 	params: Record<string, string>;
 	locals: Locals;
+	platform: Platform;
 }
 
 export interface ResolveOpts {
 	ssr?: boolean;
 }
 
-export interface Handle<Locals = Record<string, any>> {
+export interface Handle<Locals = Record<string, any>, Platform = Record<string, any>> {
 	(input: {
-		event: RequestEvent<Locals>;
-		resolve(event: RequestEvent<Locals>, opts?: ResolveOpts): MaybePromise<Response>;
+		event: RequestEvent<Locals, Platform>;
+		resolve(event: RequestEvent<Locals, Platform>, opts?: ResolveOpts): MaybePromise<Response>;
 	}): MaybePromise<Response>;
 }
 ```
@@ -84,8 +85,8 @@ If unimplemented, SvelteKit will log the error with default formatting.
 
 ```ts
 // Declaration types for handleError hook
-export interface HandleError<Locals = Record<string, any>> {
-	(input: { error: Error & { frame?: string }; event: RequestEvent<Locals> }): void;
+export interface HandleError<Locals = Record<string, any>, Platform = Record<string, any>> {
+	(input: { error: Error & { frame?: string }; event: RequestEvent<Locals, Platform> }): void;
 }
 ```
 
@@ -107,8 +108,12 @@ If unimplemented, session is `{}`.
 
 ```ts
 // Declaration types for getSession hook
-export interface GetSession<Locals = Record<string, any>, Session = any> {
-	(event: RequestEvent<Locals>): Session | Promise<Session>;
+export interface GetSession<
+	Locals = Record<string, any>,
+	Platform = Record<string, any>,
+	Session = any
+> {
+	(event: RequestEvent<Locals, Platform>): MaybePromise<Session>;
 }
 ```
 
@@ -125,7 +130,7 @@ export function getSession(event) {
 					email: event.locals.user.email,
 					avatar: event.locals.user.avatar
 				}
-			}
+		  }
 		: {};
 }
 ```

documentation/docs/10-adapters.md

@@ -93,6 +93,7 @@ Within the `adapt` method, there are a number of things that an adapter should d
   - Imports `App` from `${builder.getServerDirectory()}/app.js`
   - Instantiates the app with a manifest generated with `builder.generateManifest({ relativePath })`
   - Listens for requests from the platform, converts them to a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) if necessary, calls the `render` function to generate a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) and responds with it
+  - `render` optionally accepts a `platform` object, which allows passing of environment specific values and functions. The `platform` object will be accessible from the handle hook and any API endpoints in the application
   - Globally shims `fetch` to work on the target platform, if necessary. SvelteKit provides a `@sveltejs/kit/install-fetch` helper for platforms that can use `node-fetch`
 - Bundle the output to avoid needing to install dependencies on the target platform, if necessary
 - Put the user's static files and the generated JS/CSS in the correct location for the target platform

packages/adapter-cloudflare/README.md

@@ -50,6 +50,28 @@ When configuring your project settings, you must use the following settings:
 
 > **Important:** You need to add a `NODE_VERSION` environment variable to both the "production" and "preview" environments. You can add this during project setup or later in the Pages project settings. SvelteKit requires Node `14.13` or later, so you should use `14` or `16` as the `NODE_VERSION` value.
 
+## Platform
+
+The handler that is outputed by the build will pass in the env object from cloudflare pages into the `platform` variable. You can read more about what env is [here](https://developers.cloudflare.com/pages/platform/functions#adding-bindings). This allows access to KV and Durable Objects from any hook or endpoint handler.
+
+```ts
+interface Env {
+	COUNTER: DurableObjectNamespace;
+}
+
+interface Locals {
+	// Locals set in locals hook
+}
+
+interface Platform {
+	env: Env;
+}
+
+export async function post<Locals, Platform>({ request, platform }) {
+	const counter = platform.env.COUNTER.idFromName('A');
+}
+```
+
 ## Changelog
 
 [The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-cloudflare/CHANGELOG.md).

packages/adapter-cloudflare/files/worker.js

@@ -45,7 +45,7 @@ export default {
 
 		// dynamically-generated pages
 		try {
-			return await app.render(req);
+			return await app.render(req, { platform: { env } });
 		} catch (e) {
 			return new Response('Error rendering route: ' + (e.message || e.toString()), { status: 500 });
 		}

packages/adapter-node/README.md

@@ -84,6 +84,27 @@ MY_ORIGINURL=https://my.site \
 node build
 ```
 
+## Platform
+
+The handler that is outputed by the build will pass in the original Node request object into the `platform` variable. This means that it can be accessed from all hooks and endpoint handlers. This is particually useful if previous middleware has added values to the request object.
+
+```ts
+import { Request } from 'polka';
+
+interface Locals {
+	// Locals set in locals hook
+}
+
+interface Platform {
+	req: Request;
+}
+
+// If using cookie-parser middleware
+export async function post<Locals, Platform>({ request, platform }) {
+	const cookies = platform.req.cookies;
+}
+```
+
 ## Custom server
 
 The adapter creates two files in your build directory — `index.js` and `handler.js`. Running `index.js` — e.g. `node build`, if you use the default build directory — will start a server on the configured port.

packages/adapter-node/src/handler.js

@@ -45,7 +45,7 @@ const ssr = async (req, res) => {
 		return res.end(err.reason || 'Invalid request body');
 	}
 
-	setResponse(res, await app.render(request));
+	setResponse(res, await app.render(request, { platform: { req } }));
 };
 
 /** @param {import('polka').Middleware[]} handlers */

packages/kit/src/core/build/build_server.js

@@ -93,14 +93,12 @@ export class App {
 		};
 	}
 
-	render(request, {
-		prerender
-	} = {}) {
+	render(request, options = {}) {
 		if (!(request instanceof Request)) {
 			throw new Error('The first argument to app.render must be a Request object. See https://github.com/sveltejs/kit/pull/3384 for details');
 		}
 
-		return respond(request, this.options, { prerender });
+		return respond(request, this.options, options);
 	}
 }
 `;
@@ -169,7 +167,6 @@ export async function build_server(
 		return relative_file[0] === '.' ? relative_file : `./${relative_file}`;
 	};
 
-	// prettier-ignore
 	fs.writeFileSync(
 		input.app,
 		template({

packages/kit/src/runtime/server/index.js

@@ -60,7 +60,8 @@ export async function respond(request, options, state = {}) {
 		request,
 		url,
 		params: {},
-		locals: {}
+		locals: {},
+		platform: state.platform
 	};
 
 	// TODO remove this for 1.0

packages/kit/types/app.d.ts

@@ -1,15 +1,19 @@
 import { PrerenderOptions, SSRNodeLoader, SSRRoute } from './internal';
 
+export interface RequestOptions<Platform = Record<string, any>> {
+	platform?: Platform;
+}
+
 export class App {
 	constructor(manifest: SSRManifest);
-	render(request: Request): Promise<Response>;
+	render(request: Request, options?: RequestOptions): Promise<Response>;
 }
 
 export class InternalApp extends App {
 	render(
 		request: Request,
-		options?: {
-			prerender: PrerenderOptions;
+		options?: RequestOptions & {
+			prerender?: PrerenderOptions;
 		}
 	): Promise<Response>;
 }

packages/kit/types/endpoint.d.ts

@@ -13,8 +13,12 @@ export interface Fallthrough {
 	fallthrough: true;
 }
 
-export interface RequestHandler<Locals = Record<string, any>, Output extends Body = Body> {
-	(event: RequestEvent<Locals>): MaybePromise<
+export interface RequestHandler<
+	Locals = Record<string, any>,
+	Platform = Record<string, any>,
+	Output extends Body = Body
+> {
+	(event: RequestEvent<Locals, Platform>): MaybePromise<
 		Either<Response | EndpointOutput<Output>, Fallthrough>
 	>;
 }

packages/kit/types/hooks.d.ts

@@ -2,39 +2,47 @@ import { MaybePromise } from './helper';
 
 export type StrictBody = string | Uint8Array;
 
-export interface RequestEvent<Locals = Record<string, any>> {
+export interface RequestEvent<Locals = Record<string, any>, Platform = Record<string, any>> {
 	request: Request;
 	url: URL;
 	params: Record<string, string>;
 	locals: Locals;
+	platform: Readonly<Platform>;
 }
 
-export interface GetSession<Locals = Record<string, any>, Session = any> {
-	(event: RequestEvent<Locals>): MaybePromise<Session>;
+export interface GetSession<
+	Locals = Record<string, any>,
+	Platform = Record<string, any>,
+	Session = any
+> {
+	(event: RequestEvent<Locals, Platform>): MaybePromise<Session>;
 }
 
 export interface ResolveOpts {
 	ssr?: boolean;
 }
 
-export interface Handle<Locals = Record<string, any>> {
+export interface Handle<Locals = Record<string, any>, Platform = Record<string, any>> {
 	(input: {
-		event: RequestEvent<Locals>;
-		resolve(event: RequestEvent<Locals>, opts?: ResolveOpts): MaybePromise<Response>;
+		event: RequestEvent<Locals, Platform>;
+		resolve(event: RequestEvent<Locals, Platform>, opts?: ResolveOpts): MaybePromise<Response>;
 	}): MaybePromise<Response>;
 }
 
 // internally, `resolve` could return `undefined`, so we differentiate InternalHandle
 // from the public Handle type
-export interface InternalHandle<Locals = Record<string, any>> {
+export interface InternalHandle<Locals = Record<string, any>, Platform = Record<string, any>> {
 	(input: {
-		event: RequestEvent<Locals>;
-		resolve(event: RequestEvent<Locals>, opts?: ResolveOpts): MaybePromise<Response | undefined>;
+		event: RequestEvent<Locals, Platform>;
+		resolve(
+			event: RequestEvent<Locals, Platform>,
+			opts?: ResolveOpts
+		): MaybePromise<Response | undefined>;
 	}): MaybePromise<Response | undefined>;
 }
 
-export interface HandleError<Locals = Record<string, any>> {
-	(input: { error: Error & { frame?: string }; event: RequestEvent<Locals> }): void;
+export interface HandleError<Locals = Record<string, any>, Platform = Record<string, any>> {
+	(input: { error: Error & { frame?: string }; event: RequestEvent<Locals, Platform> }): void;
 }
 
 export interface ExternalFetch {

packages/kit/types/internal.d.ts

@@ -141,6 +141,7 @@ export interface SSRRenderOptions {
 export interface SSRRenderState {
 	fetched?: string;
 	initiator?: SSRPage | null;
+	platform?: any;
 	prerender?: PrerenderOptions;
 	fallback?: string;
 }