Middleware

Middleware helps with code reuse and orchestrating more sophisticated request pipelines. Webroute offers a simple, powerful and novel approach to middleware to avoid some of the pitfalls of previous approaches.

Overview

Webroute's approach to middleware is highly functional. Instead of middleware imperatively orchestrating the app, it is a pure function which merely accepts inputs and returns outputs. Consequently, many of the common bugs are avoided.

This approach means middleware are always strongly type-safe and connected in-code. Our routes will alway know what middleware runs before it and what state middleware may or may not provide.

Getting Started

To register a middleware function, we use the .use() method. The handler we provide takes the same parameters as a request handler.

route().use((req, c) => {
  console.log("URL:", req.url);
});

Middleware works incredibly well with the composition pattern.

const routeWithMiddleware = route().use((req) => {
  console.log("URL:", req.url);
});
 
const oneRoute = routeWithMiddleware.handle(() => {});
const anotherRoute = routeWithMiddleware.handle(() => {});

Middleware Effects

Most middleware wants to change or orchestrate our app somehow. Because web-standard Requests are immutable, we can't directly modify the Request object. Moreover, webroute doesn't provide any function like next() to orchestrate the app flow. Instead, webroute uses return values to enable these actions.

Updating Request State

A common use-case of middleware is adding some information to our request. In other words, we are storing some state about the current request. We can return a plain JavaScript object to indicate a state update is in order. Webroute will read the type of the object, which will be reflected in future access of the state property.

route()
  .use((req, { state }) => {
    return { elvenBreadCount: 3 };
  })
  .handle((req, { 
state: {
    elvenBreadCount: number;
}state }) => {
  });

State updates from additional middleware will be shallow merged with the request state.

Early Response

Middleware is commonly used to guard subsequent handlers by returning a response early under some condition. For example authentication and authorisation middleware.

If we return a Response from middleware, this will trigger an early response.

route()
  .use((req, { state }) => {
    if (req.headers.get("x-is-balrog")) {
      return new Response("You shall not pass.", { status: 401 });
    }
    return { isAragon: true };
  })
  .handle((req, { state }) => {
    return "You passed.";
  });

Response Handlers

Another use for middleware is to listen to and potentially alter the Response on its way out. Such response handlers are the third and final variant a middleware can return. Response handlers are functions which accept a Response as the only parameter. They may optionally return an updated Response.

route().use((req, { state }) => {
  const start = Date.now();
 
  return (response) => {
    console.log("Took", Date.now() - start);
 
    return new Response(response.body, { status: 203 });
  };
});

Escape Hatch: Mutating State

Most of the time, middleware will only need to do one of these three things at once. They are almost mutually exclusive options. However, in rare cases we may want to update request state and return early or handle responses.

In this case, we can use the escape hatch of mutating state directly, i.e. without returning. Not only can we mutate state, but we can do so without sacrificing type-safety.

route()
  .use<{ hasRing: boolean }>((req, c) => {
    const stateMut = c.state as any;
    stateMut.hasRing = false;
 
    return new Response("OK");
  })
  .handle((req, c) => {
    const { 
const hasRing: booleanhasRing } = c.state;
  });

Here we provide a generic type parameter indicating how our states type will change.

Defining Middleware

While creating middleware inline is a valid approach, it makes reusing middleware more difficult. Instead, we can define middleware elsewhere.

As we've seen, middleware is inherently basic, so we can define middleware like so.

export const myMiddleware = (req: Request) => {
  // Implement middleware
};

Instead of making our middleware reliant on the context param, we encourage specifically defining only what is needed. This helps with testing and will make your code less fragile.

A Realistic Example

So far the examples have been relatively contrived. Here is a more realistic glimpse at what working with middleware might look like.

const bearerToken = (req: Request) => {
  return {
    bearerToken: req.headers.get("Authorization")?.replace("Bearer", "").trim(),
  };
};
 
const isAuthed = (req: Request, bearerToken?: string) => {
  try {
    const { id } = verifyJwt(bearerToken);
    return { userId: id };
  } catch (e) {
    return new Response("Unauthorized", { status: 401 });
  }
};
 
const authedRoute = route()
  .use(bearerToken)
  // Pass data as needed
  .use((req, c) => isAuthed(req, c.state.bearerToken));
 
const myRoute = authedRoute.path("/foo").handle((req, c) => {
  const { 
const userId: stringuserId } = c.state;
});