Astro middleware

[pilcrowOnPaper]

Summary

Introduce a middleware to Astro, where you can define code that runs on every request. This API should work regardless of the rendering mode (SSG or SSR) or adapter used. Also introduces a simple way to share request-specific data between proposed middleware, API routes, and .astro routes.

Background & Motivation

Middleware has been one of the most heavily requested feature in Astro. It's useful for handling common tasks like auth guards and setting cache headers. For me, it would make handling authentication much easier.

This proposal is heavily inspired by SvelteKit's handle hooks.

Goals

• Provide a way intercept requests and responses, allowing users to set cookies and headers
• Works both in SSR and SSG mode
• Allow users to use community-created middlewares (libraries)
• Provide an API for request-specific data

Non-goals

• Route specific middleware

Example

A quick prototype

Middlewares can be defined in src/middleware.ts by exporting middleware (array):

export cost middleware = []

A simple middleware looks like so:

export const middleware: Middleware = async (context: APIContext, resolve: Resolve) => {
  const session = await getSession(context.request);
  const isProtectedRoute = matchRoute(context.url);
  if (!session && isProtectedRoute) {
    // early response
    return new Response(null, {
      status: 400,
    });
  }
  context.cookies.set("random-cookie", "some-value");
  const response = await resolve(context); // resolve api route or render page
  return response;
};

context is the same one provided to API route handlers. Most of Astro's request handling process will be behind resolve(), and the response object returned from middleware will be sent to the user's browser.

Multiple middleware

sequence can be imported to run multiple middlewares in sequence.

export const middleware: Middleware = sequence(
  async (context, resolve) => {
    console.log("1a");
    const response = await resolve(event);
    console.log("1b");
    return response;
  },
  async (context, resolve) => {
    console.log("2a");
    const response = await resolve(event);
    console.log("2b");
    return response;
  }
);

The log result for this example is:

1a
2a
2b
1b

locals

This proposal also adds locals property to APIContext and AsroGlobal. This locals object will be forwarded across the request handling process, allowing for data to be shared between middlewares, API routes, and .astro pages. This is useful for storing request specific data, such as user data, across the rendering step.

export const middleware = async (context: APIContext, resolve: Resolve) => {
  context.session = await getSession(context.request);
  const response = await resolve(context);
  return response;
};

---
// pages/index.astro
const session = Astro.locals.session;
---

The value type of locals can be anything as it won't be JSON-stringified:

---
// pages/index.astro
const session = await Astro.locals.getSession();
---

locals can be typed inside src/env.d.ts (I think it's possible?):

// src/env.d.ts
// at least one of these should be possible
type Locals {}

declare namespace App {
    type Locals = {}
}

SSG mode

The middleware function will run on each route's pre-rendering step, as if it were handling a normal SSR request.

export const middleware = async (context: APIContext, resolve: Resolve) => {
  const response = await resolve(context); // pre-render step here
  return response;
};

[pilcrowOnPaper]

One common pattern for middleware found in Express and Next.js looks something like this:

const middleware = (req, res, next) => {
  // do stuff
  if (condition) {
    next();
  }
};

However, this is only possible because Node native request/response API is used. Since Astro uses web standard Request and Response, a different approach was needed.

[natemoo-re]

I like this a lot! Thanks for sharing the proposal. 🙌🏻

Enforcing namespaces is something I'd want to factor into the proposal to avoid collisions as much as possible. Type-safety is also very important for DX, so I'd love if we could do this in a type-safe way.

Here's a quick experiment in that vein on the TypeScript Playground. I've implemented "locals" (renamed to "data") with namespacing.

Providers (middleware) could register their "data" using the following pattern, ensuring that their data is properly namespaced.

interface AuthData {
    user: { name: string };
    authenticated: boolean;
}

declare module 'astro:middleware' {
  interface Register {
    "@acme/auth-middleware": AuthData
  }
}

Consumers (user, other middleware) could then read from "data" in a type-safe way.

// Get all data
const { authenticated, username } = context.data.get('@acme/auth-middleware');
// Get specific nested key
const username = context.data.get('@acme/auth-middleware', 'user.name');

This is possibly by using a NamespacedMap class, which could look something like:

type Key = string|number|symbol;
class NamespacedMap<TNamepsace extends Key, TData extends Record<Key, any>> {
    #data: Record<TNamepsace, TData> = {} as any;
    set(namespace: TNamepsace, value: TData): void;
    set<TKey extends keyof TData>(namespace: TNamepsace, key: TKey, value: TData[TKey]): void;
    set(namespace: TNamepsace, ...args: any): void {
        if (args.length === 0) throw new Error('TODO');
        if (args.length === 1) {
            const [value] = args;
            this.#data[namespace] = value;
            return;
        }
        if (args.length === 2) {
            // TODO: handle dot syntax
            const [key, value] = args as [keyof TData, TData[keyof TData]];
            this.#data[namespace][key] = value;
            return;
        }
    }

    get(namespace: TNamepsace): TData;
    get<TKey extends keyof TData>(namespace: TNamepsace, key: TKey): TData[TKey];
    get(namespace: TNamepsace, ...args: any): any {
        if (args.length === 0) return this.#data[namespace];
        // TODO: handle dot syntax
        const [key] = args as [keyof TData];
        return this.#data[namespace][key];
    }
}

[pilcrowOnPaper]

I actually like the idea of using maps! It's like an import statement, but for using data from middleware instead of modules.

I think NamespacedMap.set doesn't have to be complicated though, and it should be limited to just a key value pair. There's no way for TS to check that the middleware set every properties registered if you allow values to be defined using dot syntax:

context.data.set('@astrojs/auth', "username", "houston_bot");
// ts doesn't realize I didn't set "@astrojs/auth.authenticated"

context.data.set('@astrojs/auth', {
  username: "houston_bot" // ts error - you're missing "authenticated"!
})

As for the name, I don't have strong preferences but I chose locals since people who've used Express or SvelteKit will feel familiar, and it's a name that is easy to remember but still distinct.

[pilcrowOnPaper]

That said, I think locals/data can also be used to pass data between .astro components as well, so I don't think it should be middleware specific.

[matthewp]

I think this makes the API significantly more cumbersome and collisions aren't super likely to begin with. I think this is a problem to solve once we encounter it, not one to anticipate.

We should try to figure out a way to make Astro.locals strongly typed, if possible though. Maybe a middleware provider can modify the type to add their own data properties?

[thdxr]

This is something we would require to allow for some of the magic that SST does to make sure things work the same in dev and when released. We have a whole hooks system that needs to be booted up when an request comes in

[jamesarosen]

I built and maintained a middleware system for use in Cloudflare workers, which uses the service-worker environment. The API for that system was (FetchEvent, (FetchEvent) => Response) => Promise<Response>. Some examples:

export async function preventFraming(fetchEvent: FetchEvent, next: Middleware) {
  const upstreamResponse = await next(fetchEvent)
  if (!upstreamResponse.headers.has('x-frame-options') {
    upstreamResponse.headers.set('x-frame-options', 'DENY')
  }
  return upstreamResponse
}

export async function adminAuth(fetchEvent: FetchEvent, next: Middleware) {
  const { pathname } = new URL(fetchEvent.request.url)
  if (!/^\/admin\//.test(pathname)) return next(fetchEvent)

  const rawJWT = fetchEvent.request.headers.get('jwt')
  if (!rawJWT) {
    return new Response('Unauthorized', { status: 401 })
  }

  const jwt = await parseJWT(rawJWT)
  if (jwt?.payload?.roles?.indexOf('admin:read') ?? -1 === -1) {
    return new Response('Forbidden', { status: 403 })
  }

  return next(fetchEvent)
}

I like this API because it's closely tied to open standards (Request, Response, FetchEvent), small, and very flexible. We can add extra context to fetchEvent if we want to expose Astro APIs to the middleware.

They also compose easily with reduce:

const BOTTOM_OF_STACK = ({ request }): FetchEvent => fetch(request) // or Astro.handle or whatever

function compose(...stack) {
  return stack.reduce((next, current) => (e) => current(e, next), BOTTOM_OF_STACK)
}

[matthewp]

I like this idea a lot, I think it's on the right track. Couple of questions:

1. How can adapters provide data for locals? One use-case we hear about a lot is wanting runtimes like Cloudflare which have their own special APIs to add data that components can then use.
2. We should talk about the different ways to register a middleware. The src/middlewares is what you suggest here, but I could also see this being done via integrations and/or config. middlewares: []. Maybe there are other ways.

[matthewp]

edit: scratched out a question that is covered in the non-goals section

[matthewp]

This proposal has been accepted and has moved into stage 2: #531