Add new fields to API route context

.changeset/fifty-ads-march.md

@@ -0,0 +1,7 @@
+---
+'astro': minor
+---
+
+Add `site`, `generator`, `url`, `clientAddress`, `props`, and `redirect` fields to API route context.
+
+Check out the docs for more information: https://docs.astro.build/en/core-concepts/endpoints/#server-endpoints-api-routes

.changeset/selfish-foxes-bake.md

@@ -0,0 +1,5 @@
+---
+'astro': minor
+---
+
+Support passing a custom status code for Astro.redirect

packages/astro/src/@types/astro.ts

@@ -94,7 +94,8 @@ export interface BuildConfig {
  * [Astro reference](https://docs.astro.build/reference/api-reference/#astro-global)
  */
 export interface AstroGlobal<Props extends Record<string, any> = Record<string, any>>
-	extends AstroGlobalPartial {
+	extends AstroGlobalPartial,
+		AstroSharedContext<Props> {
 	/**
 	 * Canonical URL of the current page.
 	 * @deprecated Use `Astro.url` instead.
@@ -107,21 +108,13 @@ export interface AstroGlobal<Props extends Record<string, any> = Record<string,
 	 * ```
 	 */
 	canonicalURL: URL;
-	/** The address (usually IP address) of the user. Used with SSR only.
-	 *
-	 */
-	clientAddress: string;
 	/**
 	 * A full URL object of the request URL.
 	 * Equivalent to: `new URL(Astro.request.url)`
 	 *
 	 * [Astro reference](https://docs.astro.build/en/reference/api-reference/#url)
 	 */
-	/**
-	 * Utility for getting and setting cookies values.
-	 */
-	cookies: AstroCookies;
-	url: URL;
+	url: AstroSharedContext['url'];
 	/** Parameters passed to a dynamic page generated using [getStaticPaths](https://docs.astro.build/en/reference/api-reference/#getstaticpaths)
 	 *
 	 * Example usage:
@@ -138,9 +131,9 @@ export interface AstroGlobal<Props extends Record<string, any> = Record<string,
 	 * <h1>{id}</h1>
 	 * ```
 	 *
-	 * [Astro reference](https://docs.astro.build/en/reference/api-reference/#params)
+	 * [Astro reference](https://docs.astro.build/en/reference/api-reference/#astroparams)
 	 */
-	params: Params;
+	params: AstroSharedContext['params'];
 	/** List of props passed to this component
 	 *
 	 * A common way to get specific props is through [destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment), ex:
@@ -150,7 +143,7 @@ export interface AstroGlobal<Props extends Record<string, any> = Record<string,
 	 *
 	 * [Astro reference](https://docs.astro.build/en/core-concepts/astro-components/#component-props)
 	 */
-	props: Props;
+	props: AstroSharedContext<Props>['props'];
 	/** Information about the current request. This is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object
 	 *
 	 * For example, to get a URL object of the current URL, you can use:
@@ -184,11 +177,11 @@ export interface AstroGlobal<Props extends Record<string, any> = Record<string,
 	 *
 	 * [Astro reference](https://docs.astro.build/en/guides/server-side-rendering/#astroredirect)
 	 */
-	redirect(path: string): Response;
+	redirect: AstroSharedContext['redirect'];
 	/**
 	 * The <Astro.self /> element allows a component to reference itself recursively.
 	 *
-	 * [Astro reference](https://docs.astro.build/en/guides/server-side-rendering/#astroself)
+	 * [Astro reference](https://docs.astro.build/en/guides/api-reference/#astroself)
 	 */
 	self: AstroComponentFactory;
 	/** Utility functions for modifying an Astro component’s slotted children
@@ -1085,8 +1078,6 @@ export type PaginateFunction = (data: any[], args?: PaginateOptions) => GetStati
 
 export type Params = Record<string, string | number | undefined>;
 
-export type Props = Record<string, unknown>;
-
 export interface AstroAdapter {
 	name: string;
 	serverEntrypoint?: string;
@@ -1096,12 +1087,111 @@ export interface AstroAdapter {
 
 type Body = string;
 
-export interface APIContext {
+// Shared types between `Astro` global and API context object
+interface AstroSharedContext<Props extends Record<string, any> = Record<string, any>> {
+	/**
+	 * The address (usually IP address) of the user. Used with SSR only.
+	 */
+	clientAddress: string;
+	/**
+	 * Utility for getting and setting cookies values.
+	 */
 	cookies: AstroCookies;
-	params: Params;
+	/**
+	 * Information about the current request. This is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object
+	 */
 	request: Request;
+	/**
+	 * A full URL object of the request URL.
+	 */
+	url: URL;
+	/**
+	 * Parameters passed to a dynamic page generated.
+	 */
+	params: Params;
+	/**
+	 * List of props passed.
+	 */
+	props: Props;
+	/**
+	 * Redirect to another page (**SSR Only**)
+	 */
+	redirect(path: string, status?: number): Response;
+}
+
+export interface APIContext<Props extends Record<string, any> = Record<string, any>>
+	extends AstroSharedContext<Props> {
+	site: URL | undefined;
+	generator: string;
+	/**
+	 * A full URL object of the request URL.
+	 * Equivalent to: `new URL(request.url)`
+	 */
+	url: AstroSharedContext['url'];
+	/**
+	 * Parameters passed to a dynamic page generated using `getStaticPaths`.
+	 *
+	 * Example usage:
+	 * ```ts
+	 * export function getStaticPaths() {
+	 *   return [
+	 *     { params: { id: '0' }, props: { name: 'Sarah' } },
+	 *     { params: { id: '1' }, props: { name: 'Chris' } },
+	 *     { params: { id: '2' }, props: { name: 'Fuzzy' } },
+	 *   ];
+	 * }
+	 *
+	 * export async function getStaticProps({ params }) {
+	 *  return {
+	 * 	  body: `Hello user ${params.id}!`,
+	 *  }
+	 * }
+	 * ```
+	 *
+	 * [context reference](https://docs.astro.build/en/guides/api-reference/#contextparams)
+	 */
+	params: AstroSharedContext['params'];
+	/**
+	 * List of props passed from `getStaticPaths`.
+	 *
+	 * Example usage:
+	 * ```ts
+	 * export function getStaticPaths() {
+	 *   return [
+	 *     { params: { id: '0' }, props: { name: 'Sarah' } },
+	 *     { params: { id: '1' }, props: { name: 'Chris' } },
+	 *     { params: { id: '2' }, props: { name: 'Fuzzy' } },
+	 *   ];
+	 * }
+	 *
+	 * export function get({ props }) {
+	 *   return {
+	 *     body: `Hello ${props.name}!`,
+	 *   }
+	 * }
+	 * ```
+	 *
+	 * [context reference](https://docs.astro.build/en/guides/api-reference/#contextprops)
+	 */
+	props: AstroSharedContext<Props>['props'];
+	/**
+	 * Redirect to another page.
+	 *
+	 * Example usage:
+	 * ```ts
+	 * // src/pages/secret.ts
+	 * export function get({ redirect }) {
+	 *   return redirect('/login');
+	 * }
+	 * ```
+	 *
+	 * [context reference](https://docs.astro.build/en/guides/api-reference/#contextredirect)
+	 */
+	redirect: AstroSharedContext['redirect'];
 }
 
+export type Props = Record<string, unknown>;
+
 export interface EndpointOutput {
 	body: Body;
 	encoding?: BufferEncoding;

packages/astro/src/cli/index.ts

@@ -22,7 +22,8 @@ import { enableVerboseLogging, nodeLogDestination } from '../core/logger/node.js
 import { formatConfigErrorMessage, formatErrorMessage, printHelp } from '../core/messages.js';
 import { appendForwardSlash } from '../core/path.js';
 import preview from '../core/preview/index.js';
-import { ASTRO_VERSION, createSafeError } from '../core/util.js';
+import { ASTRO_VERSION } from '../core/constants.js';
+import { createSafeError } from '../core/util.js';
 import * as event from '../events/index.js';
 import { eventConfigError, eventError, telemetry } from '../events/index.js';
 import { check } from './check/index.js';

packages/astro/src/core/constants.ts

@@ -0,0 +1,2 @@
+// process.env.PACKAGE_VERSION is injected when we build and publish the astro package.
+export const ASTRO_VERSION = process.env.PACKAGE_VERSION ?? 'development';

packages/astro/src/core/endpoint/dev/index.ts

@@ -8,5 +8,7 @@ export async function call(ssrOpts: SSROptions) {
 	return await callEndpoint(mod as unknown as EndpointHandler, {
 		...ssrOpts,
 		ssr: ssrOpts.settings.config.output === 'server',
+		site: ssrOpts.settings.config.site,
+		adapterName: ssrOpts.settings.config.adapter?.name,
 	});
 }

packages/astro/src/core/endpoint/index.ts

@@ -4,6 +4,9 @@ import type { RenderOptions } from '../render/core';
 import { renderEndpoint } from '../../runtime/server/index.js';
 import { AstroCookies, attachToResponse } from '../cookies/index.js';
 import { getParamsAndProps, GetParamsAndPropsError } from '../render/core.js';
+import { ASTRO_VERSION } from '../constants.js';
+
+const clientAddressSymbol = Symbol.for('astro.clientAddress');
 
 export type EndpointOptions = Pick<
 	RenderOptions,
@@ -17,6 +20,7 @@ export type EndpointOptions = Pick<
 	| 'site'
 	| 'ssr'
 	| 'status'
+	| 'adapterName'
 >;
 
 type EndpointCallResult =
@@ -30,11 +34,50 @@ type EndpointCallResult =
 			response: Response;
 	  };
 
-function createAPIContext(request: Request, params: Params): APIContext {
+function createAPIContext({
+	request,
+	params,
+	site,
+	props,
+	adapterName,
+}: {
+	request: Request;
+	params: Params;
+	site?: string;
+	props: Record<string, any>;
+	adapterName?: string;
+}): APIContext {
 	return {
 		cookies: new AstroCookies(request),
 		request,
 		params,
+		site: site ? new URL(site) : undefined,
+		generator: `Astro v${ASTRO_VERSION}`,
+		props,
+		redirect(path, status) {
+			return new Response(null, {
+				status: status || 302,
+				headers: {
+					Location: path,
+				},
+			});
+		},
+		url: new URL(request.url),
+		get clientAddress() {
+			if (!(clientAddressSymbol in request)) {
+				if (adapterName) {
+					throw new Error(
+						`clientAddress is not available in the ${adapterName} adapter. File an issue with the adapter to add support.`
+					);
+				} else {
+					throw new Error(
+						`clientAddress is not available in your environment. Ensure that you are using an SSR adapter that supports this feature.`
+					);
+				}
+			}
+
+			return Reflect.get(request, clientAddressSymbol);
+		},
 	};
 }
 
@@ -49,9 +92,15 @@ export async function call(
 			`[getStaticPath] route pattern matched, but no matching static path found. (${opts.pathname})`
 		);
 	}
-	const [params] = paramsAndPropsResp;
+	const [params, props] = paramsAndPropsResp;
 
-	const context = createAPIContext(opts.request, params);
+	const context = createAPIContext({
+		request: opts.request,
+		params,
+		props,
+		site: opts.site,
+		adapterName: opts.adapterName,
+	});
 	const response = await renderEndpoint(mod, context, opts.ssr);
 
 	if (response instanceof Response) {

packages/astro/src/core/render/core.ts

@@ -68,7 +68,7 @@ export async function getParamsAndProps(
 }
 
 export interface RenderOptions {
-	adapterName: string | undefined;
+	adapterName?: string;
 	logging: LogOptions;
 	links: Set<SSRElement>;
 	styles?: Set<SSRElement>;

packages/astro/src/core/render/result.ts

@@ -196,9 +196,9 @@ export function createResult(args: CreateResultArgs): SSRResult {
 				request,
 				url,
 				redirect: args.ssr
-					? (path: string) => {
+					? (path: string, status?: number) => {
 							return new Response(null, {
-								status: 302,
+								status: status || 302,
 								headers: {
 									Location: path,
 								},

packages/astro/src/core/util.ts

@@ -8,9 +8,6 @@ import type { ErrorPayload, ViteDevServer } from 'vite';
 import type { AstroConfig, AstroSettings, RouteType } from '../@types/astro';
 import { prependForwardSlash, removeTrailingForwardSlash } from './path.js';
 
-// process.env.PACKAGE_VERSION is injected when we build and publish the astro package.
-export const ASTRO_VERSION = process.env.PACKAGE_VERSION ?? 'development';
-
 /** Returns true if argument is an object of any prototype/class (but not null). */
 export function isObject(value: unknown): value is Record<string, any> {
 	return typeof value === 'object' && value != null;

packages/astro/src/events/index.ts

@@ -1,6 +1,6 @@
 import { AstroTelemetry } from '@astrojs/telemetry';
 import { createRequire } from 'module';
-import { ASTRO_VERSION } from '../core/util.js';
+import { ASTRO_VERSION } from '../core/constants.js';
 const require = createRequire(import.meta.url);
 
 function getViteVersion() {

packages/astro/src/runtime/server/astro-global.ts

@@ -1,7 +1,5 @@
 import type { AstroGlobalPartial } from '../../@types/astro';
-
-// process.env.PACKAGE_VERSION is injected when we build and publish the astro package.
-const ASTRO_VERSION = process.env.PACKAGE_VERSION ?? 'development';
+import { ASTRO_VERSION } from '../../core/constants.js';
 
 /** Create the Astro.fetchContent() runtime function. */
 function createDeprecatedFetchContentFn() {

packages/astro/test/fixtures/ssr-api-route/astro.config.mjs

@@ -0,0 +1,8 @@
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+
+// https://astro.build/config
+export default defineConfig({
+	output: 'server',
+	adapter: node(),
+});

packages/astro/test/fixtures/ssr-api-route/package.json

@@ -3,6 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "dependencies": {
+    "@astrojs/node": "^1.1.0",
     "astro": "workspace:*"
   }
 }

packages/astro/test/fixtures/ssr-api-route/src/pages/context/[param].js

@@ -0,0 +1,18 @@
+/**
+ * @param {import('astro').APIContext} api 
+ */
+export function get(ctx) {
+	return {
+		body: JSON.stringify({
+			cookiesExist: !!ctx.cookies,
+			requestExist: !!ctx.request,
+			redirectExist: !!ctx.redirect,
+			propsExist: !!ctx.props,
+			params: ctx.params,
+			site: ctx.site?.toString(),
+			generator: ctx.generator,
+			url: ctx.url.toString(),
+			clientAddress: ctx.clientAddress,
+		})
+	};
+}