Astro API Endpoint Middleware RFC proposal.

[michaelgrigoryan25]

Hello everyone, I hope you are all doing well and safe. I'd like to begin by thanking everyone involved with Astro for your hard work and dedication; you guys have done an excellent job!

Currently, if we want authentication around our desired routes, we must create a separate function:

// lib/wrappers.ts
import type { APIContext } from "astro";
export async function withAuth(ctx: APIContext) { /** ... */ }

and call it from our endpoint the following way:

// pages/api/index.ts
import type { APIRoute } from "astro";
import { withAuth } from "~/lib/wrappers";

export const post: APIRoute = async (ctx) => {
    const user = await withAuth(ctx);
    // ...
};

We're currently doing this with multiple middleware handlers, so one handles authentication, another handles parsing the JSON payload from the request body, and so on.

// lib/wrappers.ts
export function withJsonPayload<T>(
  handle: (props: { ctx: APIContext; payload: T }) => Response | EndpointOutput | Promise<Response | EndpointOutput>
) {
  return async (ctx: APIContext) => {
    try {
      const raw = await ctx.request.text();
      const payload = JSON.parse(raw);
      return await handle({ ctx, payload });
    } catch (error) {
      console.error(error);
      return new Response(JSON.stringify(error), { status: 400 });
    }
  };
}

and in our endpoints we define it the following way:

// pages/api/index.ts
export const post = withAuth(
  async ({ user, ctx }) =>
    await withJsonPayload(async ({ payload }) => { /** ... */ })(ctx)
);

This works. However, as you can imagine, this can become overly complex when used with more middleware handlers that contain much more code. One of my ideas is to have a function mwrap() (or something similar) which will take the middleware logic, wrap it internally (perhaps with some metadata, so that Astro can treat it as a middleware), and store the state returned from the middleware in a separate state key on the request ctx. Or in case we want to short-circuit the request, return a Response.

import { APIContext, EndpointOutput, Response } from "astro";

export async function mwrap<T>(
    fn: (ctx: APIContext) =>
                    T | Response | EndpointOutput
          | Promise<T | Response | EndpointOutput>
) { /** ... */ }

When creating middleware, we will define our function the following way:

import { mwrap } from "astro";
export const withJsonPayload = mwrap((ctx) => { /** ... */ });

Finally, in our endpoint file, we would use our middleware the following way:

import type { APIRoute } from "astro";
import { withAuth, withJsonPayload } from "~/lib/wrappers";

export const post: APIRoute = withAuth(withJsonPayload(async (ctx) => { /** ... */ }))

Just so everyone is aware, I am completely willing to work on this RFC. However, more feedback in this discussion section and approval from the maintainers would have been ideal. I'd appreciate if you left some of your comments or suggestions about this proposal below.

[natemoo-re]

I would love to have first-class support for this! I also think this might be prototypable in userland, which is really exciting. 🎉

Take a look at how our @astrojs/vue integration uses the virtual: entrypoint to surface user-configured entrypoints and expose them to our internals—I could totally see an @astrojs/middleware integration do something similar.
https://github.com/withastro/astro/blob/main/packages/integrations/vue/src/index.ts#L35

[matthewp]

Cool API idea, this has come up a lot so I think we definitely should start working on something for middleware. Couple of things that we talked about on the call:

1. Where is the hook that Astro has to know about these functions that are created? We usually avoid globals in the Astro codebase and it seems like this API design might necessity it.
2. How can adapters participate?
3. These examples show using it with API routes; how do you use this in a .astro page?

[michaelgrigoryan25]

Thank you everyone for your comments and prompt feedback @natemoo-re @matthewp. To address the questions brought up above, I have composed a list of some initial solutions.

Initial implementation.

One way I see the implementation of the Middleware RFC for Astro Pages and Endpoints, would be to have separate files for middleware, such as /pages/<route>.middleware.ts for Astro pages, and /pages/api/<route>.middleware.ts for API Endpoints. Ideally, we could have support for multiple HTTP methods (GET, POST, etc.) in the /pages/api/<route>.middleware.ts file, by exporting named functions.

// /pages/api/index.middleware.ts
import { APIContext } from "astro";

export const get = (ctx: APIContext) => { ... };
export const post = (ctx: APIContext) => { ... };

In the best case scenario, if one does not really care about the HTTP method used while sending a request to a specific route, and wants to apply the middleware to all the requests regardless of the method, they could just export a named all function from the middleware file:

// /pages/api/index.middleware.ts
import { APIContext } from "astro";

export const all = (ctx: APIContext) => { ... };

Alternative implementation.

Suppose we have defined a custom middleware with mwrap() in the following way:

import { mwrap } from "astro";

export const withAuth = mwrap(async (ctx) => { ... });
/// ...

The way mwrap() would work, is that it would allow the defined middleware logic to return any type of native Astro response such as EndpointOutput or Response, so the developers will not be limited in any way.

Then in the /pages/api/index.middleware.ts file, we would import our middleware function wrapped with mwrap, and just include it in an exported variable named with the HTTP method, in the following way:

import { withAuth, withJsonPayload } from "<wrapped-middleware-definition-path>";

export const all = [withAuth];
export const post = [withJsonPayload];

Middleware state persistence.

One of the most important things in this RFC which would need implementation would be exposing a state API from the APIContext (a.k.a the request context) to set some values in a dedicated object such as state (ctx.state. APIContext["state"]) which would be passed around from request to request.

For example, if one would want to have a payload object in their state after parsing JSON with a designated middleware, they will be able to set it just by ctx.state.append({ payload: { ... } })-ing it, after which they would have access to the payload object from all the paths that the middleware has access to. Same applies to the user middleware.

Regarding the second question, I have not really considered using provider-specific middleware implementations such as CloudFlare Middleware Functions, nor do I have any experience in using them.

[ShivamJoker]

Having middle-wares is really a nice idea, although there should be some config which should allow us to define which middle-ware goes where.

We usually avoid globals in the Astro codebase and it seems like this API design might necessity it.

We need to have a global config or something where we could define a matching pattern for the routes and based on that we could add middlewares.

Because if go with the @michaelgrigoryan25 approach /pages/api/<route>.middleware.ts we will be having so many duplicate files.

[michaelgrigoryan25]

Because if go with the @michaelgrigoryan25 approach /pages/api/.middleware.ts we will be having so many duplicate files.

The middleware files will be applied to all the nested routes. So, for example, if you have a middleware file in the /api/reports/ directory, then it will be applied to /api/reports/*. Then, if you add another type of middleware, specific to a certain route for example /api/reports/cars/, then the middleware of /api/reports/* will run first, then /api/reports/cars/* middleware will run after it.

We need to have a global config or something where we could define a matching pattern for the routes and based on that we could add middlewares.

Having a global config like in Next.js would not be really useful in my opinion, because after all Astro is a an MPA not SPA. In case of Next.js only SPAs are intended and they define all the logic in a single middleware file, instead of organizing them in subroutes. I feel that having a single/global middleware file will not be scalable and will be hard to maintain.

[ShivamJoker]

Makes sense! but what if we wanted to exclude some routes?

[michaelgrigoryan25]

You still would be able to separate the routes, place them in different directories, or to individual routes. We could also include an exlcude directive from the middleware file, which would also make sense. Here is an exmaple:

export const all: APIMiddleware = [...];

export const config: APIMiddlewareConfig = {
    exclude: ["/<path>"] // which would evaluate to /api/<route-with-middleware>/<path> 
};

We could also have individual configurations for each HTTP method, which would be even more powerful.

[ShivamJoker]

This looks perfect.
Can't wait to see this feature getting added in astro.

[anuragk15]

Sounds so awesome. Any idea when we can see this?

[michaelgrigoryan25]

Don't really know how to approach this currently, since I'm not familiar with the internals of Astro, @anuragk15.