Decisions

[cyco130]

There are a few decisions to make:

1. How should the middleware signature be?
   • Easy to grasp: (req, ctx) => Response | undefined. If undefined is returned, next middleware is run. You can change req and ctx fields to do useful stuff (e.g. parse cookies and pur it in ctx.cookies).
   • More useful: (req, ctx, next) => Response. next gives you the ability to manipulate the response, e.g. add security headers but it's more awkward to use.
   • Combine the two? Returning undefined does the same thing as return next(). Fatih's preference
2. How can we provide a chainable response builder? (middlewares can extend it so you can do: ctx.response("body").type("application/html").cookie("session", { secure: true, ... })
   • All chains are required to end with build(): return builder().xxx().yyy().build() (so that it returns a Response instance instead of a builder instance).
   • We accept any object with a toResponse() method in addition to plain Response. Fatih's preference
3. How to handle errors? (no real preference on this one)
   • Leave it to the user, they have to wrap everything in try/catch or do things like return next().catch(error => ...). We only provide a last resort 500 response.
   • ctx.addErrorHandler(), handlers are called (last added first) until one handles the error and returns a response.
   • (maybe in addition to other strategies) check if the thrown error has a toResponse() method: It makes validation errors very easy to handle (just implement MyValidationLibraryError.prototype.toResponse. Also allows "throwing" responses (useful in some cases).

[brillout]

1. I'm leaning towards the first option: do we really need an extra function next() in hatTip's world? The ctx is basically a "fourre-tout" for anything that it outside the Fetch API spec scope. I'm thinking, if we can consolidate all utils in ctx, that could be nice?

2. Do we need chains? Why not just new Response()? For middlewares, maybe something like this:

ctx.response.setCookie("session", { secure: true, ... })

So basically:

• new Response() => creates the final response object (compliant with the Fetch API spec)
• ctx.response./*...*/ => sets "defaults" for the response object (the user / the last middleware can override these and has full control with new Response())

3. How about this:

• ctx.errorList => all errors that occurred during the entire request-response lifecycle.
• ctx.err => the last error.
• hatTip provides a onError(middleware) utility that essentially just makes sure that middleware is run last. The middleware can then read ctx.err/ctx.errorList, use an error tracking service such as sentry, and/or gracefully handle the erroneous state.

[cyco130]

1. I implemented (locally for now) ctx.next() and added unit tests. It also solves 3, at least for now (return ctx.next().catch(err => ...)). But when writing the tests, I forgot twice to return something from a handler (which is currently equivalent to returning ctx.next()). If I made this simple mistake twice, I'm sure people will make it all the time and curse our names :) Perhaps the types shouldn't allow it and we should require that handlers that don't want to handle the request to explicitly return ctx.next()? Or at least some other value than undefined like return null?

[brillout]

I also really like the idea of always enforcing a return value 👌.

I like the simplicity of return null. So yea, why not just return null. Bonus: by avoiding using ctx, it makes the middleware seam more Fetch API compliant.