Should a middleware (provided by a library) that selectively responds to requests always call next()?

[benjie]

Hi folks; I maintain a project called PostGraphile which helps build powerful GraphQL APIs backed primarily by a Postgres database. PostGraphile supports many webserver frameworks, including Koa, through adaptors. PostGraphile handles calls to /graphql (the API) and /graphiql (the IDE) and a couple other URLs, but selectively. For example, POST requests to /graphiql are not handled, and GET requests to /graphql may or may not be handled.

Here's some pseudocode to give you the flavour of what's going on. In PostGraphile we might have:

export const postgraphileMiddleware = async (ctx, next) => {
  const response = await getPostGraphileResponseFromKoa(ctx);
  if (response) {
    // PostGraphile has a response for this request; send the response and stop.
    const { headers, statusCode, body } = response;
    ctx.response.set(headers);
    ctx.response.status = statusCode;
    ctx.response.body = body;
  } else {
    // PostGraphile doesn't want to handle this request; pass on to downstream middleware.
    return next();
  }
};

And in user code:

import Koa from 'koa';
import { postgraphileMiddleware } from "postgraphile/servers/koa"; // NOT REAL!

const app = new Koa();

// app.use(compress());
// app.use(logging());
// ...

app.use(postgraphileMiddleware);

// ...

From the docs/guide.md file:

Middleware that decide to respond to a request and wish to bypass downstream middleware may simply omit next(). Typically this will be in routing middleware, but this can be performed by any.
-- https://github.com/koajs/koa/blob/master/docs/guide.md#response-middleware

My understanding from reading the above is that response middleware can choose whether or not to call next(), and that because of the nested structure of Koa both "before" and "after" actions can be accomplished by adding Koa middleware before the PostGraphile middleware is added - therefore there's no need to call next() for common concerns such as instrumentation, logging, compression, etc. It thus made sense to me for PostGraphile to only call next() if it isn't handling the request, that way downstream middleware won't accidentally overwrite PostGraphile's response thinking that it hadn't already been handled.

However, a user has complained that this isn't the case, and that a middleware provided by a library should always call next() whether or not it's a response middleware, and that the only people who should be allowed to not call next() are the end users composing the middlewares.

I'd like to get a project maintainer's input on this, and would be happy to contribute the conclusion back to the response middleware part of the guide.md file. In particular, if next() should always be called by a library middleware then what is the standard practice for users to protect themselves from handling the same request multiple times (e.g. overwriting the body)? I'll probably need to add those details to PostGraphile's documentation.

Please note that PostGraphile can respond in a large number of ways, including things like a HTTP 204 with no content (i.e. ctx.response.body = null), and streaming responses (ctx.response.body = stream).

Thanks for your input on this.