From cb1fb5737c65d9389ca4790a1ae9932abebe5bbe Mon Sep 17 00:00:00 2001 From: Arsh <69170106+lilnasy@users.noreply.github.com> Date: Fri, 12 Jan 2024 23:32:07 +0530 Subject: [PATCH 01/11] Adapter enhancements in Astro 4.2 --- .../docs/en/reference/adapter-reference.mdx | 40 ++++++++++++++++++- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 04a4e574ad87b..0fa7da0dca9b5 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -194,7 +194,7 @@ export function start(manifest) { The following methods are provided: -##### `app.render(request, { routeData, locals })` +##### `app.render(request: Request, options?: RenderOptions)` This method calls the Astro page that matches the request, renders it, and returns a Promise to a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object. This also works for API routes that do not render pages. @@ -202,10 +202,46 @@ This method calls the Astro page that matches the request, renders it, and retur const response = await app.render(request); ``` -The method accepts a mandatory `request` argument, and an optional argument for [`routeData`](/en/reference/integrations-reference/#routedata-type-reference) and [`locals`](/en/reference/api-reference/#astrolocals). +##### `RenderOptions` + +The `app.render()` method accepts a mandatory `request` argument, and an optional argument for [`clientAddress`](/en/reference/api-reference/#astroclientaddress),[`locals`](/en/reference/api-reference/#astrolocals), [`routeData`](/en/reference/integrations-reference/#routedata-type-reference). + +###### `addCookieHeader` + +Whether to automatically add all cookies written by `Astro.cookie.set()` to the response headers. +When set to `true`, they will be added to the `Set-Cookie` header of the response as comma-separated key=value pairs. You can use the standard `response.headers.getSetCookie()` API to read them individually. +When set to `false`(default), the cookies will only be available from `App.getSetCookieFromResponse(response)`. + +```js +const response = await app.render(request, { addCookieHeader: true }); +``` + +###### `clientAddress` + +The client IP address that will be made available as `Astro.clientAddress` in pages, and as `ctx.clientAddress` in API routes and middleware. + +The example below reads `x-forwarded-for` header and passes it as `clientAddress`, Astro makes this value available to the user as `Astro.clientAddress`. +```js +const clientAddress = request.headers.get("x-private-header"); +const response = await app.render(request, { clientAddress }); +``` + +###### `routeData` Provide a value for `routeData` if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. +```js +const routeData = app.match(request); +if (routeData) { + return app.render(request, { routeData }); +} else { + /* adapter-specific 404 response */ + return new Response(..., { status: 404 }); +} +``` + +###### `locals` + The example below reads a header named `x-private-header`, attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). ```js From eb2212b77da65e2106c1a048d9c7ddba67a391d5 Mon Sep 17 00:00:00 2001 From: Arsh <69170106+lilnasy@users.noreply.github.com> Date: Sat, 13 Jan 2024 07:19:04 +0530 Subject: [PATCH 02/11] Apply suggestions from code review Co-authored-by: Alex Nguyen --- src/content/docs/en/reference/adapter-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 0fa7da0dca9b5..8ef5dbec7285a 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -222,7 +222,7 @@ The client IP address that will be made available as `Astro.clientAddress` in pa The example below reads `x-forwarded-for` header and passes it as `clientAddress`, Astro makes this value available to the user as `Astro.clientAddress`. ```js -const clientAddress = request.headers.get("x-private-header"); +const clientAddress = request.headers.get("x-forwarded-for"); const response = await app.render(request, { clientAddress }); ``` From 229c0e702b06264287c67247b2eeebfff147ae8e Mon Sep 17 00:00:00 2001 From: Arsh <69170106+lilnasy@users.noreply.github.com> Date: Mon, 15 Jan 2024 23:19:33 +0530 Subject: [PATCH 03/11] Apply suggestions from code review Co-authored-by: Sarah Rainsberger Co-authored-by: voxel!() --- src/content/docs/en/reference/adapter-reference.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 8ef5dbec7285a..995b8d5cf514a 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -204,11 +204,12 @@ const response = await app.render(request); ##### `RenderOptions` -The `app.render()` method accepts a mandatory `request` argument, and an optional argument for [`clientAddress`](/en/reference/api-reference/#astroclientaddress),[`locals`](/en/reference/api-reference/#astrolocals), [`routeData`](/en/reference/integrations-reference/#routedata-type-reference). +The `app.render()` method accepts a mandatory `request` argument, and an optional argument for [`clientAddress`](/en/reference/api-reference/#astroclientaddress), [`locals`](/en/reference/api-reference/#astrolocals), and [`routeData`](/en/reference/integrations-reference/#routedata-type-reference). ###### `addCookieHeader` -Whether to automatically add all cookies written by `Astro.cookie.set()` to the response headers. +Whether or not to automatically add all cookies written by `Astro.cookie.set()` to the response headers. + When set to `true`, they will be added to the `Set-Cookie` header of the response as comma-separated key=value pairs. You can use the standard `response.headers.getSetCookie()` API to read them individually. When set to `false`(default), the cookies will only be available from `App.getSetCookieFromResponse(response)`. @@ -220,8 +221,8 @@ const response = await app.render(request, { addCookieHeader: true }); The client IP address that will be made available as `Astro.clientAddress` in pages, and as `ctx.clientAddress` in API routes and middleware. -The example below reads `x-forwarded-for` header and passes it as `clientAddress`, Astro makes this value available to the user as `Astro.clientAddress`. -```js +The example below reads the `x-forwarded-for` header and passes it as `clientAddress`. This value becomes available to the user as `Astro.clientAddress`. +```js "clientAddress" const clientAddress = request.headers.get("x-forwarded-for"); const response = await app.render(request, { clientAddress }); ``` @@ -230,7 +231,7 @@ const response = await app.render(request, { clientAddress }); Provide a value for `routeData` if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. -```js +```js "routeData" const routeData = app.match(request); if (routeData) { return app.render(request, { routeData }); @@ -244,7 +245,7 @@ if (routeData) { The example below reads a header named `x-private-header`, attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). -```js +```js "locals" const privateHeader = request.headers.get("x-private-header"); let locals = {}; try { From ef48d6e322b889e8989f90a53249ad58f88c2190 Mon Sep 17 00:00:00 2001 From: lilnasy <69170106+lilnasy@users.noreply.github.com> Date: Mon, 15 Jan 2024 18:20:10 +0000 Subject: [PATCH 04/11] routeData, locals -> locals, routeData --- .../docs/en/reference/adapter-reference.mdx | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 995b8d5cf514a..6ee7b48893c90 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -227,20 +227,6 @@ const clientAddress = request.headers.get("x-forwarded-for"); const response = await app.render(request, { clientAddress }); ``` -###### `routeData` - -Provide a value for `routeData` if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. - -```js "routeData" -const routeData = app.match(request); -if (routeData) { - return app.render(request, { routeData }); -} else { - /* adapter-specific 404 response */ - return new Response(..., { status: 404 }); -} -``` - ###### `locals` The example below reads a header named `x-private-header`, attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). @@ -257,6 +243,20 @@ try { } ``` +###### `routeData` + +Provide a value for `routeData` if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. + +```js "routeData" +const routeData = app.match(request); +if (routeData) { + return app.render(request, { routeData }); +} else { + /* adapter-specific 404 response */ + return new Response(..., { status: 404 }); +} +``` + ##### `app.match(request)` This method is used to determine if a request is matched by the Astro app's routing rules. From baae8872f162162c9e961f30e07efb7920109d0f Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 17 Jan 2024 12:44:12 -0400 Subject: [PATCH 05/11] thanks for the complex punctuation Arsh --- src/content/docs/en/reference/adapter-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 6ee7b48893c90..13d1e5b9075d1 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -210,7 +210,7 @@ The `app.render()` method accepts a mandatory `request` argument, and an optiona Whether or not to automatically add all cookies written by `Astro.cookie.set()` to the response headers. -When set to `true`, they will be added to the `Set-Cookie` header of the response as comma-separated key=value pairs. You can use the standard `response.headers.getSetCookie()` API to read them individually. +When set to `true`, they will be added to the `Set-Cookie` header of the response as comma separated key-value pairs. You can use the standard `response.headers.getSetCookie()` API to read them individually. When set to `false`(default), the cookies will only be available from `App.getSetCookieFromResponse(response)`. ```js From f750a7a10786b5595b9a5d250e3909d5a6829072 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 17 Jan 2024 12:45:14 -0400 Subject: [PATCH 06/11] line spacing --- src/content/docs/en/reference/adapter-reference.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 13d1e5b9075d1..938d0a83fa5cc 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -222,6 +222,7 @@ const response = await app.render(request, { addCookieHeader: true }); The client IP address that will be made available as `Astro.clientAddress` in pages, and as `ctx.clientAddress` in API routes and middleware. The example below reads the `x-forwarded-for` header and passes it as `clientAddress`. This value becomes available to the user as `Astro.clientAddress`. + ```js "clientAddress" const clientAddress = request.headers.get("x-forwarded-for"); const response = await app.render(request, { clientAddress }); From 834ac33b4f585206652d2f700d5b138b50f323f5 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 17 Jan 2024 12:49:12 -0400 Subject: [PATCH 07/11] explain/link what locals is before the example --- src/content/docs/en/reference/adapter-reference.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 938d0a83fa5cc..37ac4125f72ad 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -230,6 +230,7 @@ const response = await app.render(request, { clientAddress }); ###### `locals` +The [`context.locals` object](/en/reference/api-reference/#contextlocals) used to store and access information during the lifecycle of a request. The example below reads a header named `x-private-header`, attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). ```js "locals" From 2586ea98480c89e58083ad6ff618d74d29420230 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 17 Jan 2024 12:49:36 -0400 Subject: [PATCH 08/11] line spacing --- src/content/docs/en/reference/adapter-reference.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 37ac4125f72ad..cdc9811b70e4e 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -231,6 +231,7 @@ const response = await app.render(request, { clientAddress }); ###### `locals` The [`context.locals` object](/en/reference/api-reference/#contextlocals) used to store and access information during the lifecycle of a request. + The example below reads a header named `x-private-header`, attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). ```js "locals" From 2c5fd5044f9d20f21397d9f5c0d2431035ee4ff4 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 17 Jan 2024 17:23:18 +0000 Subject: [PATCH 09/11] updates link strategy --- src/content/docs/en/reference/adapter-reference.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index cdc9811b70e4e..40a9eef138694 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -204,7 +204,7 @@ const response = await app.render(request); ##### `RenderOptions` -The `app.render()` method accepts a mandatory `request` argument, and an optional argument for [`clientAddress`](/en/reference/api-reference/#astroclientaddress), [`locals`](/en/reference/api-reference/#astrolocals), and [`routeData`](/en/reference/integrations-reference/#routedata-type-reference). +The `app.render()` method accepts a mandatory `request` argument, and an optional `RenderOptions` object for [`addCookieHeader`](#addcookieheader), [`clientAddress`](#clientaddress), [`locals`](#locals), and [`routeData`](/#routedata). ###### `addCookieHeader` @@ -219,7 +219,7 @@ const response = await app.render(request, { addCookieHeader: true }); ###### `clientAddress` -The client IP address that will be made available as `Astro.clientAddress` in pages, and as `ctx.clientAddress` in API routes and middleware. +The client IP address that will be made available as []`Astro.clientAddress`](/en/reference/api-reference/#astroclientaddress) in pages, and as `ctx.clientAddress` in API routes and middleware. The example below reads the `x-forwarded-for` header and passes it as `clientAddress`. This value becomes available to the user as `Astro.clientAddress`. @@ -248,7 +248,7 @@ try { ###### `routeData` -Provide a value for `routeData` if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. +Provide a value for []`routeData`](/en/reference/integrations-reference/#routedata-type-reference) if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. ```js "routeData" const routeData = app.match(request); From 1fb54a5e467485f2a9d2faf0eb420a9ae7a0b192 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 17 Jan 2024 17:25:07 +0000 Subject: [PATCH 10/11] fix link --- src/content/docs/en/reference/adapter-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 40a9eef138694..b62a0a4d920e2 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -204,7 +204,7 @@ const response = await app.render(request); ##### `RenderOptions` -The `app.render()` method accepts a mandatory `request` argument, and an optional `RenderOptions` object for [`addCookieHeader`](#addcookieheader), [`clientAddress`](#clientaddress), [`locals`](#locals), and [`routeData`](/#routedata). +The `app.render()` method accepts a mandatory `request` argument, and an optional `RenderOptions` object for [`addCookieHeader`](#addcookieheader), [`clientAddress`](#clientaddress), [`locals`](#locals), and [`routeData`](#routedata). ###### `addCookieHeader` From e0b9ca2a530919f3595db045a65e1b2fc9d3839f Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 17 Jan 2024 17:26:26 +0000 Subject: [PATCH 11/11] fix more stupid links --- src/content/docs/en/reference/adapter-reference.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index b62a0a4d920e2..3dd96383161dc 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -219,7 +219,7 @@ const response = await app.render(request, { addCookieHeader: true }); ###### `clientAddress` -The client IP address that will be made available as []`Astro.clientAddress`](/en/reference/api-reference/#astroclientaddress) in pages, and as `ctx.clientAddress` in API routes and middleware. +The client IP address that will be made available as [`Astro.clientAddress`](/en/reference/api-reference/#astroclientaddress) in pages, and as `ctx.clientAddress` in API routes and middleware. The example below reads the `x-forwarded-for` header and passes it as `clientAddress`. This value becomes available to the user as `Astro.clientAddress`. @@ -248,7 +248,7 @@ try { ###### `routeData` -Provide a value for []`routeData`](/en/reference/integrations-reference/#routedata-type-reference) if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. +Provide a value for [`routeData`](/en/reference/integrations-reference/#routedata-type-reference) if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. ```js "routeData" const routeData = app.match(request);