Separation of Handlers from Middleware, and next delegate from Context

[mindplay-dk]

Just a thought: your Handler is actually what would be called Middleware in other frameworks.

Broadly, a "handler" is a Request => Response function, and "middleware" is a Handler => Handler function that performs a simple functional composition.

So I would like to suggest a formal definition of an actual Handler as something separate (and lower level) from Middleware, as most frameworks generally have.

Basically:

1. Remove next from Context.
2. Make this next delegate part of a formal Middleware interface definition:

export type Middleware = (next: Handler) => Handler;

This way, a Middleware is just a factory for a Handler - and now you have a Handler that is guaranteed to return, can't delegate to any next handler.

The distinction is useful because your 404 handler, and controllers in general, cannot and should not delegate - these are examples of handlers that must return a Response.

This removes the need for errors/exceptions when running middleware - and you get a runHandler that better reflects the reality that you can't actually have a middleware-stack without a final-handler... so, something like:

function runHandler(
  middleware: Iterable<Middleware>,
  final: Handler,
  request: Request,
  context: Context,
) { ... }

This means you can get rid of the default 404 handler that's built-in - or at least make it plainly visible that one is required.

This probably removes the need for isNotFound in Context and some conditions and relying on console.error in compose.ts.

On the adapter side, this tends to simplify things a bit, since a Handler is more or less plainly callable.

Middleware becomes more of a userland concept - an implementation detail, as far as how users choose to create and compose handlers, while the framework itself can internally rely mostly on Handler, which would simplify some things.

Thoughts? 🙂

[cyco130]

I do agree separating Middleware and Handler type definitions might make sense but I don't see the advantage of your version over ctx.next(). Here's a simple middleware implementation in both versions:

function cookieParser(req, ctx) {
  ctx.cookie = cookie.parse(req.headers.get("cookie") || "");
}

(This works because returning undefined is equivalent to return ctx.next() (types suggest return null is required but it's gonna change).

vs

function cookieParser(next) {
  return (req, ctx) => {
    ctx.cookie = cookie.parse(req.headers.get("cookie") || "");
    return next();
  }
}

In my opinion, the first one is:

• Easier to read.
• More similar to Express so people familiar with it (e.g. every single Node developer :D) could easily relate to it.
• Compatible with existing tools like itty-router (it forwards extra args so ctx is not a problem).

I'm not particularly concerned about blurring the distinction between handlers and middleware. "Call each handler until one returns a response" is a very simple mental model.

isNotFound is a mechanism I was experimenting with for a very particular use case: using a HatTip handler/handler stack as an Express middleware. In that case we don't want to return a 404 response but let Express's next handler handle the case. isNotFound is how the adapter knows the default 404 handler was called and that it should not call res.write / res.end.

The use case is important for adoption: It allows people who can't live without a specific Express middleware to adopt HatTip even before that functionality becomes available natively. It's also important because I'm basing the next version of my Vite-based React framework Rakkas on HatTip and Express interoperability is a frequently requested feature. (HatTip integration is happening on the next branch).

The "last resort" error handler and console.error doesn't have much to do with this issue. But yes, it probably belongs to the adapters, not to compose.

By the way the readme is a bit out of date: User code rarely needs compose at all, you can export a (deep) array of handlers now.

What particular aspect of the second version do you think is better compared to the first version?

[mindplay-dk]

Your second example is not quite correct - next is a Handler, it's not a closure bound to existing objects:

function cookieParser(next) {
  return (req, ctx) => {
    ctx.cookie = cookie.parse(req.headers.get("cookie") || "");
    return next(req, ctx);
  }
}

In TypeScript, I would write this out as:

const cookieParser: Middleware = (next) => (req, ctx) => {
  ctx.cookie = cookie.parse(req.headers.get("cookie") || "");
  return next(req, ctx);
}

I think this is more explicit and transparent - it doesn't hide any of the facts from you, and I believe it gives you more control.

It's more verbose, sure - but there is less to explain. How does next find the request? How does the context get passed to next without my passing it? What happens if I don't call next? Removing the need to rely on side-effects, in favor of pure functions, can remove some of this complexity, while simplifying the types (avoiding unions) and improving type safety:

const cookieParser: Middleware = (next) => (req, ctx) => {
  return next(
    req,
    { ...ctx, cookie: cookie.parse(req.headers.get("cookie") || "")) }
  );
}

The Request and Response types are immutable - with your example, how would you be able to modify the request before passing to the next function? I don't think you can?

In keeping with immutability, which encourages pure functions with no side-effects, I think it would be natural if Context was also immutable.

If Handler and Middleware could be described as pure functions, we could even potentially get around the need to "lie" about the Context type and risking collisions - I mean this:

hattip/packages/router/ambient.d.ts

Lines 3 to 8 in e4c6d82

	declare module "@hattip/core" {
	interface Context {
	url: URL;
	params: any;
	}
	}

This isn't safe, or correct - Context does not necessarily have url and params properties, that depends on where you are in the middleware stack. You could declare them as unions with undefined, which would be more accurate, but still leads to potential collisions. You could fix that by using Symbol keys, but it will start to get rather inconvenient - and even then, you wouldn't know if url is missing because the route was unresolved or because the middleware hasn't run yet.

I know this may seem controversial, but if it comes right down to it, we're actually probably much better off without any middleware concept at all. I've always kind of viewed this as a "false convenience", because it actually adds complexity, and the types aren't accurate - little "lies" here and there to make things appear smooth on the surface, making things seems "simple", when in actuality, we're favoring "easy" over "simple", and writing middleware is actually hard because you have to know about all the hidden details.

If I could have my way (ha ha) we would have middleware, but no actual middleware "type", just handlers - these would be just functions, with signatures that accurately reflect what they require, and what they return, and you would manually compose them into a middleware stack.

Here's a quick example.

I obviously haven't thought about everything here - I left out some details for simplicity, it's just a quick draft. 🙂

Mainly, the point is to illustrate that middleware can be composed out of pure functions using immutable objects, and that this can be made completely safe. (both for the middleware consumer, and for the middleware developer.)

Try removing cookieParser from the handler at the end of the script - fooPage requires CookieContext, which is introduced by cookieParser, and so there is no hidden dependency. There's no accidentally composing a stack with fooPage without the required cookieParser. There's no composing a stack where these middlewares are composed in the wrong order.

All of these problems are possible with traditional middleware. We usually sweep these problems under the rug with lots of if-statements, fallbacks, console.error statements, run-time exceptions, etc.

This is what I mean by "false convenience". The "one middleware" signature we're used to just isn't accurate, and the reality isn't as simple as we make it out to be.

Some people don't like the "onion shape" of the handler composition at the end - which is funny, because the "onion layers" analogy is often how middleware is explained and described. Granted, an array looks nice and linear - but the reality is closer to an "onion shape" than a flat list. (More to that point, with arbitrary function signatures, you are not in fact limited to a single next handler - a given middleware could accept or require zero or two or more handlers, for example, choosing different paths through different nested middleware stacks...)

Anyhow, I know this is controversial, because the traditional "easy on the surface" middleware pattern, where middleware components are just an array, and magically (through trial-and-error on the consumer side - and painstaking, confusing effort on the middleware developers side) everything somehow (fingers crossed) integrates at run-time, is somehow really well-established. In my opinion, maybe one of the most "successfully bad ideas" out there.

I realize I'm fighting an uphill battle, but I felt it was worth discussing and hopefully not a complete waste of your time. 😅

Feel free to ignore me or debate me to death as you see fit. 🙈

[cyco130]

Feel free to ignore me or debate me to death as you see fit. see_no_evil

I'll take the latter because I almost fully agree with you, but there's a nuance :)

Your second example is not quite correct - next is a Handler, it's not a closure bound to existing objects:

This isn't very important, ctx.next() could take (optional) arguments too, but I have reasons to believe it might not be such a good idea which I'll explain in a bit.

The fact is, hapi guys are right, "middleware is just another name for bad design”. But it is so only on the application level. It's perfectly acceptable on the infrastructure level. Let me elaborate:

Node's http API is very low level. Simple things like body parsing, cookies, query strings, and sessions that work out-of-the box on environments like PHP require a lot of error-prone user level code. The Request-Response web APIs aren't much different in that regard. The flip side is, lower level libraries offer a lot more flexibility and very high performance. I think the middleware pattern should only be used to provide mid-level capabilities (cookies, sessions, etc.) on top of lower level features. It isn't meant to be used as an organizational pattern for a high level app.

The Request and Response types are immutable

Only on the surface. They have mutable internal state that's externally observable: You can only parse the body once, once you call req.text() the object is “used”, a second call will throw. The API itself isn't functional. Because of the streaming nature of HTTP, without language features like type states or monads, we can't design a strictly typed or purely functional API. What we can do is to parse the body once in a middleware and save it for later use. Depending on the nature of your application it can be as simple as ctx.body = await req.json() or contain complex content negotiation.

I liked the immutable request context idea, that's how middlewares work in current Rakkas. It's onion-style middleware layers all the way with input and output context types nesting one in other until the endpoint handler which behaves differently. Very similar to your suggestion. I built a few mid-sized apps with this system and it... turned out not as useful as I thought it would be :)

In a typical app, you need a bunch of middleware, a body parser, a cookie parser, an authentication/session manager, and maybe a few authorization guards around a group of routes. You can opt out of a few of these on some of the routes that you know don't need them for optimization but that's it: Deep nesting and differentiation is rarely necessary. That makes the strictly typed functional style unnecessarily noisy. I found that the added safety didn't justify the added noise and complexity.

Request and Response are way too low level to leak into application level code unless it's a very simple app. Therefore HatTip is also low level. You should get it, add a few middleware that is needed in your app and then build an application specific representation of a "request". Organize your app in any way you like. If it's simple enough, simple middleware pattern might suffice. If you like
you can try the typed middleware pattern you described. If it's more complex you may end up needing dependency injection (which solves the ordering problem inherent to the middleware pattern). Or maybe you use something else, it's entirely up to you :)

[cyco130]

I realize it's a disorganized brain dump. Feel free to point out bits that aren't clear :)

[mindplay-dk]

I've been pondering this.

The more I think about it, the more it seems to me that a lot of the things we try to fit to a Middleware, or just to a simple Handler interface, don't strictly fit either of those contracts.

For example, there's no reason why a cookie parser would need to return a response. Parsing cookies is just simply Response => Cookies, nothing more. To make it fit the contract, now the cookie parser has to consider a request and produce a response by delegating to some other handler.

I mean, we want to be sure we're not parsing the same request twice, so there's that - but JS being garbage-collected, "attaching" context to a request is just a simple optimization pattern that any function can easily implement using a WeakMap:

type Cookies = {
  // ...
};

const cache = new WeakMap<Request, Cookies>();

function cookies(req: Request): Cookies {
  if (! cache.has(req)) {
    cache.set(req, parseCookies(req));
  }

  return cache.get(req)!;
}

function parseCookies(req: Request): Cookies {
  return {} // ...  
}

Beyond the dependency on a request, parse functions etc. don't strictly need to be coupled to responses or delegates at all.

I'm honestly questioning why we do any of it at all.

Handlers need to exist for the sake of the server that's going to host it - but forcing everything into the shape of a handler or middleware does seem a bit like a case of Golden Hammer, if we're being completely honest, doesn't it?

I don't know, I think maybe I'm getting to a point where I've been doing this for too long. I'm afraid I'm turning into the sort of developer who is increasingly just "no" on everything and anything that begets complexity of any sort, unless it's damningly necessary.

I think I'm getting old. 😅

[cyco130]

Here's an excerpt of something I wrote during one of our chats with @brillout while discussing the basic API:

1. Use a different signature:
   1a. A single context argument that contains the request object.
   1b. A context argument in addition to the request object.
2. Hide the context in the request object:
   2a. Break the standard and use req.user or req.context.user (the Express way).
   2b. Use a private symbol and provide a getContext / setContext API to access it. i.e. const PRIVATE_SYMBOL = new Symbol(). Then access request[PRIVATE_SYMBOL], but maybe behind an API.
   2c. Use a weak map and provide a getContext / setContext API.

I guess I was getting old too :D

Aside: We had decided to go with 1b like in the current code but some experimentation with the API prompted me to reconsider and we rediscussed to settle on 1a. Not yet implemented though.

You're right that a cookie parser doesn't need to return a response. But an authentication guard does, for instance. And an "X-Powered-By: hattip" middleware (top priority :P) needs to see and modify the response as it would be returned if it didn't exist. So yes, technically these are three different concepts and each could be expressed better in a different way.

Like I said, I believe middleware is not a good pattern and we shouldn't organize our apps in terms of them. But for providing and consuming lower level services (like parsing cookies or adding CORS headers), they are easy to implement, easy to use, and easy to grasp. Tried and true as well: We can bash Express all day long and it will still be everyone's tool of choice for many years to come thanks to its simplicity, conciseness, and pragmatism.

(Until hattip catches on, that is :P )

[cyco130]

Also, while JavaScript does have the expressive power of doing things in a more functional way, most standard APIs don't. Consider a URL parser, just new URL(req.url) so you can access pathname, searchParams etc. Ideally you would want to create a single URL object and use it throughout the request/response cycle but URL is not immutable. Which means a middleware can do url.pathname = "/".

We can either fight the standard APIs and implement our own immutable URL object or embrace them and call such a middleware a "URL rewriter" :)

[mindplay-dk]

You could extract an immutable subset of a type, I suppose.

type IURL = Omit<Readonly<URL>, "searchParams"> & {
 searchParams: Omit<URL["searchParams"], "append" | "delete" | "set">;
};

I see your point though, it kind of is a fight.

On the other hand, how many things are in the Request and Response model that don't actually make sense outside of fetch?

Though I guess maybe you intend for this to work in the browser as well though, for things like service workers? So you might not have much choice in the matter, unless you're willing to really fight'em all. 😅

[cyco130]

type IURL = Omit<Readonly<URL>, "searchParams"> & {
 searchParams: Omit<URL["searchParams"], "append" | "delete" | "set">;
};

This is of course TS only, nothing stops you from modifying the URL object. Also, a usable immutable URL would have things like setSearch (or withSearch or whatever) which would return a new URL with the query string replaced. Here's an implementation of such an API.

On the other hand, how many things are in the Request and Response model that don't actually make sense outside of fetch?

Though I guess maybe you intend for this to work in the browser as well though, for things like service workers? So you might not have much choice in the matter, unless you're willing to really fight'em all. sweat_smile

I do plan to support service workers but the more important use case is the edge workers. Cloudflare is already supported and Deno (and Deno Edge) shouldn't be much harder. They already use Request and Response so the adapters are more or less no-ops.

Using Request and Response on the server-side is getting more and more common place: Svelte Kit and Remix follow the same path. So I'm fairly confident the future lies in Request/Response.